public interface UpgradeAction
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.
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.
|
void initialize(UpgradeActionContext uac, String name, AttributeValue[] properties) throws IfsException
uac
- the context of the actionname
- the name of the actionproperties
- the properties for the actionIfsException
- 82100: if the operation failsvoid analyze() throws IfsException
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.
IfsException
- 82101: if the operation failsvoid preUpgrade() throws IfsException
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.
IfsException
- 82102: if the operation failsvoid upgrade() throws IfsException
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.
IfsException
- 82103: if the operation failsvoid postUpgrade() throws IfsException
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.
IfsException
- 82104: if the operation failsvoid rollback(boolean downgrade) throws IfsException
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.
downgrade
- whether the rollback is being performed as part of
a downgradeIfsException
- 82105: if the operation failsCopyright © 2023. All rights reserved.