oracle.ifs.admin.tools.upgrade

Interface UpgradeAction

All Known Implementing Classes:

AbstractUpgradeAction, AddAttributeAction, FreeClassObjectAction, FreeServerConfigurationAction, JdbcAction, LibrarySessionAction, RemoveAttributeAction

public interface UpgradeAction

A step in a schema upgrade.

The upgrade actions performed by a schema upgrade, and the order in which they are performed, are defined by the upgrade script. For each upgrade action, the upgrade script specifies a unique name, the classname of the UpgradeAction implementation, and, optionally, one or more properties. Multiple upgrade actions may use the same UpgradeAction implementation.

Based on the upgrade script, the upgrade driver constructs the UpgradeAction implementation for each upgrade action. The UpgradeAction implementation must provide a default constructor. To perform the schema upgrade, the upgrade driver then calls the methods defined by this interface.

As a schema upgrade is performed, the upgrade driver can be repeatedly stopped and restarted. Each time the upgrade driver is restarted, a new UpgradeAction object will be constructed for the same upgrade action. As a result, an UpgradeAction implementation should not rely on member or class fields to hold state across invocations of methods in this interface. Instead, use StateAssistant to store an action's state.

(Unpublished)

Method Summary

Modifier and Type	Method and Description
void	analyze() Performs the analysis phase of an upgrade action.
void	initialize(UpgradeActionContext uac, String name, AttributeValue[] properties) Initializes the upgrade action.
void	postUpgrade() Performs the post-upgrade phase of an upgrade action.
void	preUpgrade() Performs the pre-upgrade phase of an upgrade action.
void	rollback(boolean downgrade) Performs a rollback of an upgrade action.
void	upgrade() Performs the upgrade phase of an upgrade action.

Method Detail

initialize

void initialize(UpgradeActionContext uac,
                String name,
                AttributeValue[] properties)
         throws IfsException

Initializes the upgrade action.

Parameters:

uac - the context of the action

name - the name of the action

properties - the properties for the action

Throws:

IfsException - 82100: if the operation fails

(Unpublished)

analyze

void analyze()
      throws IfsException

Performs the analysis phase of an upgrade action.

The analysis phase is the first phase of a schema upgrade. It allows an action to verify preconditions and provide estimates of the amount of work to be performed in subsequent phases (using the setPreUpgradeProgress, setUpgradeProgress, and setPostUpgradeProgress methods of ProgressAssistant).

Repository changes performed by this method MUST be fully reversed by a subsequent call to rollback.

If a fatal error is encountered, the method SHOULD call postError to post the error, then MUST throw an exception. The upgrade driver will log the exception and stop.

If a non-fatal error is encountered, the method MUST post the error, SHOULD log any exception, and MUST NOT throw an exception. The method MAY continue other parts of the analysis. When the method returns, the upgrade driver will continue the analysis phase for other upgrade actions, but will report the posted errors upon completion of the analysis phase.

If the method is long-running, it SHOULD periodically update its progress using setProgressPercentage. As a general guideline, it should update its progress every 30 seconds.

The method MUST periodically check whether the upgrade driver has been requested to stop by calling stopRequested, and if so, return as quickly as possible without throwing an exception. The upgrade driver will record that the analysis phase was interrupted. When the driver restarts, it will call analyze again to continue the analysis phase of this upgrade action.

If the method returns without posting an error, throwing an exception, or stop being called, the upgrade driver records that the analysis phase is complete for this upgrade action.

Throws:

IfsException - 82101: if the operation fails

(Unpublished)

preUpgrade

void preUpgrade()
         throws IfsException

Performs the pre-upgrade phase of an upgrade action.

The pre-upgrade phase is the second phase of a schema upgrade. It allows an action to perform work before the outage period, while end-users operate against the old software version. Work performed by pre-upgrade must therefore be transparent to the old software version. An action must also contemplate the possibility that end-user actions further update the repository after its pre-upgrade phase completes.

Unlike all other phases of an upgrade, administrators can repeat the pre-upgrade phase after its successful completion to stay "caught up" if the upgrade phase is not immediately started upon completion of the pre-upgrade phase. (However, there is still the potential for end-user updates to the repository between the final preUpdate call and invocation of the upgrade method).

Repository changes performed by this method MUST be fully reversed by a subsequent call to rollback.

If a fatal error is encountered, the method SHOULD call postError to post the error, then MUST throw an exception. The upgrade driver will log the exception and stop.

If a non-fatal error is encountered, the method MUST post the error, SHOULD log any exception, and MUST NOT throw an exception. The method SHOULD continue other parts of the pre-upgrade. When the method returns, the upgrade driver will continue the pre-upgrade phase for other upgrade actions, but will report the posted errors upon completion of the pre-upgrade phase.

If the method is long-running, it SHOULD periodically update its progress using setProgressPercentage and setPreUpgradeProgress. As a general guideline, it should update its progress every 30 seconds.

The method MUST periodically check whether the upgrade driver has been requested to stop by calling stopRequested, and if so, return as quickly as possible without throwing an exception. The upgrade driver will record that the pre-upgrade phase was interrupted. When the driver restarts, it will call preUpgrade again to continue the pre-upgrade phase of this upgrade action.

If the method returns without posting an error, throwing an exception, or stop being called, the upgrade driver records that the pre-upgrade phase is complete for this upgrade action.

Throws:

IfsException - 82102: if the operation fails

(Unpublished)

upgrade

void upgrade()
      throws IfsException

Performs the upgrade phase of an upgrade action.

The upgrade phase is the third phase of a schema upgrade. It is performed during an outage, preventing concurrent end-user access to the repository. Upon completion of the upgrade phase, the repository must be compatible with the new software version.

If a fatal error is encountered, the method SHOULD call postError to post the error, then MUST throw an exception. The upgrade driver will log the exception and stop.

If a non-fatal error is encountered, the method MUST post the error, SHOULD log any exception, and MUST NOT throw an exception. The method SHOULD NOT continue other parts of the upgrade. When the method returns, the upgrade driver will report the posted errors and stop.

If the method is long-running, it SHOULD periodically update its progress using setProgressPercentage and setUpgradeProgress. As a general guideline, it should update its progress every 30 seconds.

The method MUST periodically check whether the upgrade driver has been requested to stop by calling stopRequested, and if so, return as quickly as possible without throwing an exception. The upgrade driver will record that the upgrade phase was interrupted. When the driver restarts, it will call upgrade again to continue the upgrade phase of this upgrade action.

If the method returns without posting an error, throwing an exception, or stop being called, the upgrade driver records that the upgrade phase is complete for this upgrade action.

Throws:

IfsException - 82103: if the operation fails

(Unpublished)

postUpgrade

void postUpgrade()
          throws IfsException

Performs the post-upgrade phase of an upgrade action.

The post-upgrade phase is the fourth and final phase of a schema upgrade. It allows an action to perform work after the outage period, while end-users operate against the new software version. Work performed by post-upgrade must therefore be transparent to the new software version.

If a fatal error is encountered, the method SHOULD call postError to post the error, then MUST throw an exception. The upgrade driver will log the exception and stop.

If a non-fatal error is encountered, the method MUST post the error, SHOULD log any exception, and MUST NOT throw an exception. The method MAY continue other parts of the post-upgrade. When the method returns, the upgrade driver will report the posted errors and stop.

If the method is long-running, it SHOULD periodically update its progress using setProgressPercentage and setPostUpgradeProgress. As a general guideline, it should update its progress every 30 seconds.

The method MUST periodically check whether the upgrade driver has been requested to stop by calling stopRequested, and if so, return as quickly as possible without throwing an exception. The upgrade driver will record that the post-upgrade phase was interrupted. When the driver restarts, it will call postUpgrade again to continue the post-upgrade phase of this upgrade action.

If the method returns without posting an error, throwing an exception, or stop being called, the upgrade driver records that the post-upgrade phase is complete for this upgrade action.

Throws:

IfsException - 82104: if the operation fails

(Unpublished)

rollback

void rollback(boolean downgrade)
       throws IfsException

Performs a rollback of an upgrade action.

The method MUST undo all repository changes made by the action's analysis and pre-upgrade phases. If downgrade is true, the method must also undo all changes made by the upgrade and post-upgrade phases.

Rollback can be performed at any time between the start of the analysis phase and the start of the upgrade phase. If every action in the upgrade is downgradable, then rollback can also be performed after the start of the upgrade phase, any time up to the start of the subsequent schema upgrade's analysis phase.

If downgrade is true, then the rollback is being performed during an outage. If false, the action must allow concurrent end-user access to the repository.

If a fatal error is encountered, the method SHOULD call postError to post the error, then MUST throw an exception. The upgrade driver will log the exception and stop.

If a non-fatal error is encountered, the method MUST post the error, SHOULD log any exception, and MUST NOT throw an exception. The method MAY continue other parts of the rollback. When the method returns, the upgrade driver will report the posted errors and stop.

If the method is long-running, it SHOULD periodically update its progress using setProgressPercentage. As a general guideline, it should update its progress every 30 seconds.

The method MUST periodically check whether the upgrade driver has been requested to stop by calling stopRequested, and if so, return as quickly as possible without throwing an exception. The upgrade driver will record that the rollback was interrupted. When the driver restarts, it will call rollback again to continue rollback of this upgrade action.

If the method returns without posting an error, throwing an exception, or stop being called, the upgrade driver records that rollback is complete for this upgrade action.

Parameters:

downgrade - whether the rollback is being performed as part of a downgrade

Throws:

IfsException - 82105: if the operation fails

(Unpublished)