BatchUpdateAssistant.BatchUpdate (ecmsdk-api 3.4.0 API)

Enclosing interface:

BatchUpdateAssistant
```
public static interface BatchUpdateAssistant.BatchUpdate
```
Controls the behavior of BatchUpdateAssistant for an upgrade action.

(Unpublished)

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`FILTER_FALSE` The value, when returned by `getRowChangeInsertFilter`, `getRowChangeUpdateFilter`, or `getRowChangeDeleteFilter` causes `INSERT`ed, `UPDATE`d, or `DELETE`d rows (respectively) to not be processed by the batch update.

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`addDeletedRowToBatch(long id)` Called by BatchUpdateAssistant for each deleted row to be processed in the batch.
`void`	`addToBatch(long id)` Called by the BatchUpdateAssistant for each row to be processed in the batch.
`void`	`beginBatch(IfsConnection conn)` Called by the BatchUpdateAssistant at the start of each batch.
`void`	`completeBatch()` Called by the BatchUpdateAssistant at the end of each batch.
`void`	`executeBatch()` Called by the BatchUpdateAssistant to write all pending updates in the batch.
`String`	`getCountExpression()` Gets a SQL expression that, when evaluated during the analysis phase, is true for rows in the `base table` to be processed by this batch update.
`String`	`getPrimaryKeyColumnName()` Gets the name of the primary key column in the `base table`.
`String`	`getRowChangeDeleteFilter()` Gets a PL/SQL expression that, when evaluated by a `DELETE` trigger on the `base table`, is true if the deleted row is to be `processed` by the batch update.
`String`	`getRowChangeInsertFilter()` Gets a PL/SQL expression that, when evaluated by an `INSERT` trigger on the `base table`, is true if the new row is to be `processed` by the batch update.
`String`	`getRowChangeUpdateFilter()` Gets a PL/SQL expression that, when evaluated by an `UPDATE` trigger on the `base table`, is true if the updated row is to be `processed` by the batch update.
`int`	`getSelectBatchSize()` Gets the `SELECT` batch size, in rows.
`String`	`getSelectExpression()` Gets a SQL expression that, when evaluated during the pre-upgrade and upgrade phases, is true only for a row in the `base table` to be processed by this batch update.
`LibrarySession`	`getSession()` Gets the session used to perform the batch update.
`String`	`getTableName()` Gets the name of the base table.
`int`	`getUpdateBatchSize()` Gets the `UPDATE` batch size, in rows.
`void`	`setProgress(int phase, long rowsToUpdate, long rowsUpdated)` Called by the BatchUpdateAssistant to update the progress of the batch update.

- Field Detail
  - FILTER_FALSE
```
static final String FILTER_FALSE
```
    The value, when returned by getRowChangeInsertFilter, getRowChangeUpdateFilter, or getRowChangeDeleteFilter causes INSERTed, UPDATEd, or DELETEd rows (respectively) to not be processed by the batch update.
    
    See Also:
    
    Constant Field Values
    
    (Unpublished)
- Method Detail
  - getSession
```
LibrarySession getSession()
                   throws IfsException
```
    Gets the session used to perform the batch update.
    The session must be authorized to enter administration mode.
    
    Returns:
    
    the session
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getTableName
```
String getTableName()
             throws IfsException
```
    Gets the name of the base table.
    
    Returns:
    
    the table name
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getPrimaryKeyColumnName
```
String getPrimaryKeyColumnName()
                        throws IfsException
```
    Gets the name of the primary key column in the base table.
    The column must be convertible, using JDBC, to a Java long.
    
    Returns:
    
    the primary key column
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getCountExpression
```
String getCountExpression()
                   throws IfsException
```
    Gets a SQL expression that, when evaluated during the analysis phase, is true for rows in the base table to be processed by this batch update.
    The expression is injected into a SQL statement of form "SELECT count(*) FROM tableName WHERE countExpression", where tableName is the value returned by getTableName and countExpression is the value returned by this method.
    Unlike getSelectExpression, the expression returned by this method may estimate the number of rows to be processed. During the analysis phase, it may not be possible to evaluate the getSelectExpression expression (for example, certain columns in the select expression may not yet exist), so an approximation may be necessary.
    
    Returns:
    
    the expression, or null to indicate all rows in the table are to be updated
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getSelectExpression
```
String getSelectExpression()
                    throws IfsException
```
    Gets a SQL expression that, when evaluated during the pre-upgrade and upgrade phases, is true only for a row in the base table to be processed by this batch update.
    The expression is injected into a SQL statement of form "SELECT primaryKeyColumnName FROM tableName WHERE selectExpression AND primaryKeyColumnName > ?", where tableName is the value returned by getTableName, primaryKeyColumnName is the value returned by getPrimaryKeyColumnName, and selectExpression is the value returned by this method.
    
    Returns:
    
    the expression, or null to indicate all rows in the table are to be updated
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getRowChangeInsertFilter
```
String getRowChangeInsertFilter()
                         throws IfsException
```
    Gets a PL/SQL expression that, when evaluated by an INSERT trigger on the base table, is true if the new row is to be processed by the batch update.
    This expression can evaluate true for a superset of the rows to be processed. For each candidate row, getSelectExpression will be evaluated to determine whether that row is actually processed.
    
    Returns:
    
    the expression, or null to indicate all new rows are to be processed by this batch update, or FILTER_FALSE to indicate no new rows are to be processed by this batch update
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getRowChangeUpdateFilter
```
String getRowChangeUpdateFilter()
                         throws IfsException
```
    Gets a PL/SQL expression that, when evaluated by an UPDATE trigger on the base table, is true if the updated row is to be processed by the batch update.
    This expression can evaluate true for a superset of the rows to be processed. For each candidate row, getSelectExpression will be evaluated to determine whether that row is actually processed.
    Although this expression may be true for an update performed by an end-user, it should evaluate to false for an update performed on the base table by the batch update itself, otherwise the row may be endlessly updated by this batch update. For this reason, although returning null is allowed, it is generally unwise to do so.
    
    Returns:
    
    the expression, or null to indicate all updated rows are to be processed by this batch update, or FILTER_FALSE to indicate no updated rows are to be processed by this batch update
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getRowChangeDeleteFilter
```
String getRowChangeDeleteFilter()
                         throws IfsException
```
    Gets a PL/SQL expression that, when evaluated by a DELETE trigger on the base table, is true if the deleted row is to be processed by the batch update.
    Unlike the insert and update filters, this expression alone determines whether a deleted row is processed by the batch update; getSelectExpression is not evaluated.
    
    Returns:
    
    the expression, or null to indicate all deleted rows are to be processed by this batch update, or FILTER_FALSE to indicate no deleted rows are to be processed by this batch update
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getSelectBatchSize
```
int getSelectBatchSize()
                throws IfsException
```
    Gets the SELECT batch size, in rows.
    In each batch, up to this number of rows are SELECTed from the base table for processing by the batch update. To maximize update throughput, this value should be as large as possible without resulting in "snapshot too old" errors.
    
    Returns:
    
    the select batch size, in rows
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - getUpdateBatchSize
```
int getUpdateBatchSize()
                throws IfsException
```
    Gets the UPDATE batch size, in rows.
    In each batch, updates are written and committed after no more than this number of rows. This value therefore determines the maximum number of row-level locks held by the batch update. To maximize update throughput, this value should be as large as possible without causing excessive lock contention with end-users.
    Regardless of this value, updates are written and committed after no more than the select batch size.
    
    Returns:
    
    the update batch size, in rows
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)
  - beginBatch
```
void beginBatch(IfsConnection conn)
         throws SQLException,
                IfsException
```
    Called by the BatchUpdateAssistant at the start of each batch.
    This method allows the BatchUpdate to amortize certain processing over the batch, instead of repeating it for each row in the batch. A common use is to prepare an IfsPreparedStatement that is executed for each row in the batch.
    
    Parameters:
    
    conn - an IfsConnection
    
    Throws:
    
    SQLException - if the operation fails
    
    IfsException - if the operation fails
    
    (Unpublished)
  - addToBatch
```
void addToBatch(long id)
         throws SQLException,
                IfsException
```
    Called by the BatchUpdateAssistant for each row to be processed in the batch.
    
    Parameters:
    
    id - the primary key of the row to be processed
    
    Throws:
    
    SQLException - if the operation fails
    
    IfsException - if the operation fails
    
    (Unpublished)
  - addDeletedRowToBatch
```
void addDeletedRowToBatch(long id)
                   throws SQLException,
                          IfsException
```
    Called by BatchUpdateAssistant for each deleted row to be processed in the batch.
    Whereas addToBatch is called for each row that requires processing by the batch update, this method is called for each row deleted subsequent to the start of the batch update that satisfies the delete filter. Because the row no longer exists, it can't be "updated"; however an upgrade action can perform other processing, such as updating an ancillary table.
    
    Parameters:
    
    id - the primary key of the row to be processed
    
    Throws:
    
    SQLException - if the operation fails
    
    IfsException - if the operation fails
    
    (Unpublished)
  - executeBatch
```
void executeBatch()
           throws SQLException,
                  IfsException
```
    Called by the BatchUpdateAssistant to write all pending updates in the batch.
    As a batch of rows is processed, this method is invoked one or more times, as specified by the update batch size. At minimum, it is always called after the last row in the batch.
    This method must cause all pending updates to be applied to the database. After calling this method, the BatchUpdateAssistant will commit those changes.
    A common strategy is for each call to addToBatch (and similarly, addDeletedRowToBatch) to add changes to a JDBC batch, and for this method to execute that JDBC batch. This approach minimizes database round trips.
    
    Throws:
    
    SQLException - if the operation fails
    
    IfsException - if the operation fails
    
    (Unpublished)
  - completeBatch
```
void completeBatch()
            throws SQLException,
                   IfsException
```
    Called by the BatchUpdateAssistant at the end of each batch.
    This method allows resources acquired by beginBatch to be released.
    
    Throws:
    
    SQLException - if the operation fails
    
    IfsException - if the operation fails
    
    (Unpublished)
  - setProgress
```
void setProgress(int phase,
                 long rowsToUpdate,
                 long rowsUpdated)
          throws IfsException
```
    Called by the BatchUpdateAssistant to update the progress of the batch update.
    The values of the arguments may be estimates of overall progress. A common implementation of this method is to call methods on the ProgressAssistant to record progress.
    Parameters:
    phase - one of
    
    STATUS_ANALYZING if called from analyze,
    
    STATUS_PREUPGRADING if called from preUpgrade,
    
    STATUS_UPGRADING if called from upgrade, or
    
    STATUS_ROLLINGBACK if called from rollback
    rowsToUpdate - an estimate of the total number of rows to process
    
    rowsUpdated - an estimate of the number or rows processed so far
    
    Throws:
    
    IfsException - if the operation fails
    
    (Unpublished)

Interface BatchUpdateAssistant.BatchUpdate

Field Summary

Method Summary

Field Detail

FILTER_FALSE

Method Detail

getSession

getTableName

getPrimaryKeyColumnName

getCountExpression

getSelectExpression

getRowChangeInsertFilter

getRowChangeUpdateFilter

getRowChangeDeleteFilter

getSelectBatchSize

getUpdateBatchSize

beginBatch

addToBatch

addDeletedRowToBatch

executeBatch

completeBatch

setProgress