Configuring Persistence and Recovery

 

The following sections describe c-hub persistence and recovery:

• Persistence

• State Records

• Recovery

• Procedure for Configuring Persistence and Recovery

 

---

Persistence

If the recovery mode argument for the start-up class in the weblogic.properties file is set to ON for the c-hub, the c-hub saves the state of a c-hub component to persistent storage when it detects a state change for the component. The types of components for which the c-hub saves the component state are:

• C-hub

• C-space

• Trading partner

• Conversation

• Message

When the c-hub detects a state change for a message, the c-hub also saves the message or the message location. If large message support is enabled and the message is a large message, the c-hub saves the message location to persistent storage. Otherwise, the c-hub saves the message to persistent storage.

Persistent storage consists of a database that the c-hub accesses by means of a connection pool. Persistent storage and the repository share the same database. The c-hub creates a state record for each component that it saves to persistent storage. A state record is a row in a database table and represents an object state.

Multiple components can change state during the time that a message passes through the c-hub. The c-hub must update the persistent storage for these components as a group. If a message passes through the c-hub successfully, then the recorded changes are retained. If the message fails, then the c-hub discards the changes. To maintain and update component states as a group, the c-hub uses transactions.

The c-hub uses the database as persistent storage, which means that:

• The c-hub saves component states and message content or location from memory to the database only during normal run-time processing.

• The c-hub reads state records and message content or location from the database back into memory only during the restart/recovery phase of a new process instance in order to re-create a run-time image of the c-hub.

The c-hub persistence strategy is:

1. When the c-hub creates a component in memory, it also creates a state record for the component. When the c-hub creates a message component, it saves the message content or location in persistent storage in addition to the message state.

2. The c-hub maintains component state information in memory and synchronizes the in-memory state with the state record.

3. When a component state changes, the c-hub updates the corresponding state record. A message traveling through the system defines an action that causes the c-hub to create new components or update existing components. In turn, an action can spawn messages that define additional actions. And these actions cause more components to be created and updated. An update to a component state is complete only when the corresponding state record has been updated.

4. If the c-hub cannot successfully update a component state, the in-memory state becomes inconsistent with the corresponding state record. When this happens, the update task aborts and the c-hub instance crashes.

   Note: When a crash occurs, you must resolve the cause of the crash and reboot the WebLogic Collaborate process to recover the persistent data.

5. The only time a state record exists without a corresponding in-memory component state is during restart/recovery. In this case, the existence of the state record causes the c-hub to re-create the component. When the recovery process concludes, the c-hub updates the state record to indicate that it belongs to the new instance of the c-hub.

 

---

State Records

A state record is a row in a database table. The row contains a copy of the component state. You can use the C-Hub Administration Console to view the state of each component. For information about using the C-Hub Administration Console to monitor components, see Monitoring the C-Hub. The following table describes the state records.

Table 5-1 State Records

State Record	Description
Hub State	State of the c-hub, such as active or inactive. The Hub State record contains the last known instance count. The instance count is a counter that increases each time the c-hub is successfully booted after a crash. The first time you boot the c-hub, the c-hub sets the instance count to 100. If the c-hub crashes and then is successfully rebooted, the c-hub increments the instance count. If the c-hub terminates in an orderly shutdown, all state records are deleted and the c-hub sets the instance count to 100 when you reboot it. The c-hub stores the instance number in each state record to indicate that the state record belongs to the currently active c-hub. During recovery, the c-hub uses the instance numbers to identify the components that it needs to recover. The c-hub updates the Hub State record: After a successful c-hub boot or reboot When the c-hub state changes At c-hub shutdown
CSpace State	State of a c-space, such as active or inactive. The c-hub creates a CSpace State record when it creates a c-space. The c-hub updates the CSpace State record: When a trading partner joins or leaves the c-space After a successful recovery
Collaborator State	State of a trading partner, such as connected, registered, active, dropped out, or disconnected. The c-hub creates a Collaborator State record when a trading partner joins the c-space. The c-hub updates the Collaborator State record: When the trading partner registers or unregisters for a conversation When the trading partner leaves the c-space
Conversation State	State of an active conversation, such as initiated or terminated. The c-hub creates a Conversation State record when it creates a conversation. The c-hub updates the Conversation State record: When a participant joins the conversation When a participant leaves the conversation When the conversation changes state The c-hub purges the Conversation State record after the conversation terminates.
Persistent Message Store	State of an outstanding message as it travels through the c-hub. The c-hub creates a Persistent Message Store record when it receives a message, and purges the Persistent Message Store record after it delivers the message to all recipients.

 

---

Recovery

When you restart a c-hub, it examines persistent storage for state records. The c-hub uses the presence or absence of state records to determine the last known state of the c-hub before termination. The type of termination was one of the following:

• Orderly shutdown—An orderly shutdown is the termination of a quiescent c-hub that does not have any active participants in any c-spaces. Because there were no active participants, there were no active conversations in progress. An orderly shutdown removes all state records for the active c-hub instance from the persistent storage.

• Crash—Any termination other than an orderly shutdown is a crash. A crash leaves state records in persistent storage, which indicates that the c-hub was active when it terminated.

The goal of recovery is to reconstruct the last known stable run-time image of a c-hub after a crash so that message processing can continue. During startup, if the Hub State indicates that the c-hub crashed, then the start-up process shifts to recovery mode.

The recovery process does not rely solely on the repository data to initiate the c-hub. Instead, the recovery process reads information from persistent storage for the previous c-hub instance. The state records and the message content or location from persistent storage supersede the repository data. After copying the state records and the message content or location and re-creating the corresponding components, the recovery process reads the repository to configure the rest of the c-hub.

If a c-enabler tries to communicate with the c-hub during recovery, the c-hub sends a message to the c-enabler to wait for the conclusion of the recovery process.

 

---

Procedure for Configuring Persistence and Recovery

To configure persistence and recovery:

1. Configure the repository as described in Configuring the Repository in Setting Up the C-Hub.

2. In the weblogic.properties file, set the recovery mode argument for the Startup class:

   weblogic.system.startupArgs.WLCStartup=RecoveryMode=ON

   The recovery mode is either ON or OFF. To create and maintain persistent storage, the recovery mode must be ON. The default is OFF.

3. If you are using the Java Message Service (JMS) queue:

   1. Configure the JMS queue as described in Configuring the Java Message Service Queue in Setting Up the C-Hub.

   2. In the weblogic.properties file, set the data source for the JMS queue to the name of the JDBC connection pool. For example:

      # Data Source for JMS Queue
      weblogic.jms.connectionPool=wlcPool

Warning: After you modify the weblogic.properties file, you must reboot your system for the changes to take effect.

For more information about the weblogic.properties file, see Setting Up the C-Hub.