Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## oracle.ifs.admin.tools.upgrade
Class BatchUpdateAssistant

    public interface class 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
`static interface` | `BatchUpdateAssistant.BatchUpdate` Controls the behavior of `BatchUpdateAssistant` for an upgrade action.

Method Summary
`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

  Description copied from interface: `BatchUpdateAssistant`
  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

  Description copied from interface: `BatchUpdateAssistant`
  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

  Description copied from interface: `BatchUpdateAssistant`
  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

  Description copied from interface: `BatchUpdateAssistant`
  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)

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD