oracle.ifs.admin.tools.upgrade

Interface BatchUpdateAssistant

public interface BatchUpdateAssistant

Assists an upgrade action to perfom efficient updates of a database table with a large number of rows.

Updating a large table can take a long time to complete if a full-table scan is required to identify the rows to be updated or a large number of rows require update. Performing the update during the upgrade phase may result in an unacceptably long outage.

BatchUpdateAssistant addresses this problem by allowing most of the update to be performed during pre-upgrade. Here's how. At the beginning of the pre-upgrade phase, a trigger is attached to the base table to record any subsequent end-user changes that require a row in the table to be processed by the batch update. The pre-upgrade phase then performs one pass over the table, in primary key order and ROWNUM qualified batches, to identify rows to be updated. For each row, if a row-level lock can be acquired, the row is updated; otherwise the row is recorded for later processsing. After completing this first pass, the pre-upgrade phase performs a second pass to process rows captured by the trigger as well as rows that couldn't be locked during the first pass. For each such row, if a row-level lock can be acquired, it is updated; otherwise the row is recorded for processing later.

After completing the second pass, the pre-upgrade phase will have updated nearly all the rows requiring update. The trigger will continue to record subsequently changed rows. If pre-upgrade is re-run, only the second pass is repeated.

Similarly, during the upgrade phase, only the second pass is peformed. This executes quickly, since only a few rows require processing and the BatchUpdateAssistant knows which rows those are. Since the upgrade phase takes place during an outage, an error will be posted if a row-level lock cannot be acquired on any row requiring update. Once all remaining rows are updated without error, the trigger is dropped.

The behavior of BatchUpdateAssistant is controlled by a BatchUpdate implementation supplied by the upgrade action. In order to use BatchUpdateAssistant, an upgrade action must meet several requirements:

• The BatchUpdate implementation must provide a LibrarySession that is authorized for administration mode. Making the upgrade action subclass LibrarySessionAction is an easy way to do this.
• There must be a single base table from which rows are selected for processing based upon a SQL expression specified by the BatchUpdate implementation. (That expression may contain subqueries against other tables.) The base table must have a primary key (or a unique constraint) on a single column that can be converted, by JDBC, to a Java long.
• Given the primary key of a base table row, the BatchUpdate implementation must perform the necessary update in the context of its LibrarySession. (An IfsConnection can be used to perform JDBC operations.) This is usually an update of the base table row. However, any operation possible in the context of a LibrarySession is allowed.

As with any upgrade action, changes made by the pre-upgrade phase must not affect end-user access to the old software version. To update an existing column, it may be necessary for the pre-upgrade phase to create a new column with a temporary name and set its value for all rows, and later, during the upgrade phase outage, drop (or hide) the existing column and rename the new column.

(Unpublished)

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	BatchUpdateAssistant.BatchUpdate Controls the behavior of BatchUpdateAssistant for an upgrade action.

Method Summary

Modifier and Type	Method and Description
void	analyze(BatchUpdateAssistant.BatchUpdate batchUpdate) Called by the analyze method of an upgrade action, performs the analysis phase for the specified batch update.
boolean	preUpgrade(BatchUpdateAssistant.BatchUpdate batchUpdate) Called by the preUpgrade method of an upgrade action, performs the pre-upgrade phase for the specified batch update.
void	rollback(BatchUpdateAssistant.BatchUpdate batchUpdate) Called by the rollback method of an upgrade action, rolls back the specified batch update.
boolean	upgrade(BatchUpdateAssistant.BatchUpdate batchUpdate) Called by the upgrade method of an upgrade action, performs the upgrade phase for the specified batch update.

Method Detail

analyze

void analyze(BatchUpdateAssistant.BatchUpdate batchUpdate)
      throws IfsException

Called by the analyze method of an upgrade action, performs the analysis phase for the specified batch update.

During the analysis phase, this method:

• Estimates the number of rows to be updated (by calling getCountExpression). This estimate is informational, and only used for progress reporting.

Parameters:

batchUpdate - the batch update

Throws:

IfsException - if the operation fails

(Unpublished)

preUpgrade

boolean preUpgrade(BatchUpdateAssistant.BatchUpdate batchUpdate)
            throws IfsException

Called by the preUpgrade method of an upgrade action, performs the pre-upgrade phase for the specified batch update.

During the pre-upgrade phase, this method:

• Attaches a trigger to the base table (using RowChangeAssistant) to record subsequent end-user changes that require a row to be processed by the batch update.
• Performs a first pass over the base table, in primary key order and ROWNUM qualified batches, to identify rows to be updated (based on getSelectExpression). For each such row, if a row-level lock can be acquired, then addToBatch is called to perform the update; otherwise the row is recorded for later processsing.
• Performs a second pass to process rows captured by the trigger as well as rows that couldn't be locked during the first pass. For each such row, if a row-level lock can be acquired, then addToBatch is called to perform the update; otherwise the row is recorded for later processsing. For rows deleted subsequent to the start of the batch update, addDeletedRowToBatch is called.

If the pre-upgrade phase is later re-run, only the last step is repeated.

Parameters:

batchUpdate - the batch update

Returns:

whether the pre-upgrade phase of the batch update completed without posting an error or being stopped

Throws:

IfsException - if the operation fails

(Unpublished)

upgrade

boolean upgrade(BatchUpdateAssistant.BatchUpdate batchUpdate)
         throws IfsException

Called by the upgrade method of an upgrade action, performs the upgrade phase for the specified batch update.

During the upgrade phase, this method:

• Repeats the second pass performed by the pre-upgrade phase, to process rows captured by the trigger as well as rows that couldn't be locked during pre-upgrade. For each such row, addToBatch is called to perform the update; if a row-level lock cannot be acquired, an error is posted. For rows deleted subeqeuent to the start of the batch update, addDeletedRowToBatch is called.
• After processing all remaining rows without error, drops the trigger on the base table.

Parameters:

batchUpdate - the batch update

Returns:

whether the upgrade phase of the batch update completed without posting an error or being stopped

Throws:

IfsException - if the operation fails

(Unpublished)

rollback

void rollback(BatchUpdateAssistant.BatchUpdate batchUpdate)
       throws IfsException

Called by the rollback method of an upgrade action, rolls back the specified batch update.

During the rollback, this method:

• Drops the trigger on the base table.

Parameters:

batchUpdate - the batch update

Throws:

IfsException - if the operation fails

(Unpublished)