oracle.ifs.admin.tools.upgrade.actions

Class AbstractUpgradeAction

java.lang.Object

oracle.ifs.admin.tools.upgrade.actions.AbstractUpgradeAction

All Implemented Interfaces:

UpgradeAction

Direct Known Subclasses:

JdbcAction, LibrarySessionAction

public abstract class AbstractUpgradeAction
extends Object
implements UpgradeAction

Abstractly implements UpgradeAction, as a convenience for creating upgrade actions.

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.

(Unpublished)

Constructor Summary

Constructors

Constructor and Description
AbstractUpgradeAction() Default constructor.

Method Summary

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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

AbstractUpgradeAction

public AbstractUpgradeAction()

Default constructor.

Subclasses must have a default constructor that (implicitly or explicitly) calls this constructor.

(Unpublished)

Method Detail

initialize

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

Initializes the upgrade action.

Subclasses that override this method must call super.initialize(uac, name, properties).

Specified by:

initialize in interface UpgradeAction

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

public 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.

In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the analysis phase of the upgrade action.

Specified by:

analyze in interface UpgradeAction

Throws:

IfsException - 82101: if the operation fails

(Unpublished)

preUpgrade

public 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.

In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the pre-upgrade phase of the upgrade action.

Specified by:

preUpgrade in interface UpgradeAction

Throws:

IfsException - 82102: if the operation fails

(Unpublished)

upgrade

public 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.

In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the upgrade phase of the upgrade action.

Specified by:

upgrade in interface UpgradeAction

Throws:

IfsException - 82103: if the operation fails

(Unpublished)

postUpgrade

public 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.

In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to perform the post-upgrade phase of the upgrade action.

Specified by:

postUpgrade in interface UpgradeAction

Throws:

IfsException - 82104: if the operation fails

(Unpublished)

rollback

public 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.

In AbstractUpgradeAction, this method has no effect. Subclasses should override this method to rollback the analysis and pre-upgrade phases of the upgrade action.

Specified by:

rollback in interface UpgradeAction

Parameters:

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

Throws:

IfsException - 82105: if the operation fails

(Unpublished)

getUpgradeActionContext

protected final UpgradeActionContext getUpgradeActionContext()
                                                      throws IfsException

Gets the context of this upgrade action.

Returns:

the action context

Throws:

IfsException - if the operation fails

(Unpublished)

getName

protected final String getName()
                        throws IfsException

Gets the name of this upgrade action.

Returns:

the action name

Throws:

IfsException - if the operation fails

(Unpublished)

getProperties

protected final AttributeValue[] getProperties()
                                        throws IfsException

Gets the upgrade action properties.

Returns:

the properties

Throws:

IfsException - if the operation fails

(Unpublished)

getProperty

protected final AttributeValue getProperty(String propertyName)
                                    throws IfsException

Gets the upgrade action property with the specified name.

Parameters:

propertyName - the property name

Returns:

the property, or null if no property has that name

Throws:

IfsException - if the operation fails

(Unpublished)