public abstract class AbstractUpgradeAction extends Object implements UpgradeAction
This class is thread-safe when the schema upgrade is performed through the
UpgradeDriverManager
interface. AbstractUpgradeAction subclasses may
spawn child threads in the analyze
, preUpgrade
,
upgrade
, postUpgrade
, or rollback
methods, however all child threads must terminate before the method that
spawned them returns.
Constructor and Description |
---|
AbstractUpgradeAction()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
void |
analyze()
Performs the analysis phase of an upgrade action.
|
protected String |
getName()
Gets the name of this upgrade action.
|
protected AttributeValue[] |
getProperties()
Gets the upgrade action properties.
|
protected AttributeValue |
getProperty(String propertyName)
Gets the upgrade action property with the specified name.
|
protected UpgradeActionContext |
getUpgradeActionContext()
Gets the context of this 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.
|
public AbstractUpgradeAction()
Subclasses must have a default constructor that (implicitly or explicitly) calls this constructor.
public void initialize(UpgradeActionContext uac, String name, AttributeValue[] properties) throws IfsException
Subclasses that override this method must call
super.initialize(uac, name, properties)
.
initialize
in interface UpgradeAction
uac
- the context of the actionname
- the name of the actionproperties
- the properties for the actionIfsException
- 82100: if the operation failspublic void 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.
In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the analysis phase of the upgrade action.
analyze
in interface UpgradeAction
IfsException
- 82101: if the operation failspublic void 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.
In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the pre-upgrade phase of the upgrade action.
preUpgrade
in interface UpgradeAction
IfsException
- 82102: if the operation failspublic void 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.
In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the upgrade phase of the upgrade action.
upgrade
in interface UpgradeAction
IfsException
- 82103: if the operation failspublic void 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.
In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the post-upgrade phase of the upgrade action.
postUpgrade
in interface UpgradeAction
IfsException
- 82104: if the operation failspublic void 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.
In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to rollback the analysis and pre-upgrade phases of the upgrade action.
rollback
in interface UpgradeAction
downgrade
- whether the rollback is being performed as part of
a downgradeIfsException
- 82105: if the operation failsprotected final UpgradeActionContext getUpgradeActionContext() throws IfsException
IfsException
- if the operation failsprotected final String getName() throws IfsException
IfsException
- if the operation failsprotected final AttributeValue[] getProperties() throws IfsException
IfsException
- if the operation failsprotected final AttributeValue getProperty(String propertyName) throws IfsException
propertyName
- the property nameIfsException
- if the operation failsCopyright © 2023. All rights reserved.