oracle.ifs.admin.tools.upgrade.impl

Class UpgradeDriver

java.lang.Object

oracle.ifs.admin.tools.upgrade.impl.UpgradeDriver

All Implemented Interfaces:

UpgradeDriverManager

public class UpgradeDriver
extends Object
implements UpgradeDriverManager

The schema upgrade driver.

(Unpublished)

Field Summary

Fields inherited from interface oracle.ifs.admin.tools.upgrade.UpgradeDriverManager

TASK_ANALYZE, TASK_NONE, TASK_POSTUPGRADE, TASK_PREUPGRADE, TASK_ROLLBACK, TASK_UPGRADE

Constructor Summary

Constructors

Constructor and Description
UpgradeDriver(DataSource dataSource, InputStream upgradeScript, AttributeValue[] defaultProperties) Constructs an UpgradeDriver.

Method Summary

Modifier and Type	Method and Description
protected Connection	acquireLock() Acquires the exclusive right for the calling thread to access this UpgradeDriver's state and use its JDBC connection.
void	addUpgradeDriverListener(UpgradeDriverListener udl) Adds an UpgradeDriverListener.
boolean	analyze() Starts or continues the analysis phase of a schema upgrade.
void	dispose() Disposes this UpgradeDriverManager.
int	getCurrentTask() Gets the current task being performed by the upgrade driver.
UpgradeStatus	getMostRecentUpgrade() Gets the most-recent schema upgrade performed or attempted.
protected PreparedStatement	getPreparedStatement(String sql) Gets a PreparedStatement for the specified SQL.
UpgradeStatus[]	getUpgradeHistory() Gets the history of all schema upgrades performed or attempted, in chronological order.
protected long	getUpgradeSequenceNextValue() Returns the next value from the database sequence used for upgrades.
boolean	isDisposed() Gets whether dispose has been called on this UpgradeDriverManager.
boolean	postUpgrade() Starts or continues the post-upgrade phase of a schema upgrade.
boolean	preUpgrade() Starts, continues, or repeats the pre-upgrade phase of a schema upgrade.
protected void	releaseLock() Releases the exclusive right for the calling thread to access this UpgradeDriver's state and use its JDBC connection.
void	removeUpgradeDriverListener(UpgradeDriverListener udl) Removes an UpgradeDriverListener.
boolean	rollback(boolean offline) Starts or continues rolling back a schema upgrade.
protected static void	rollbackTransaction(Connection conn) Rolls-back the specified connection's transaction, best efforts.
void	stop() Requests the in-progress analyze, preUpgrade, upgrade, postUpgrade, or rollback to stop.
String	toStatusLabel(int status) Gets a string representation of the specified status value.
String	toTaskLabel(int task) Gets a string representation of the specified task value.
boolean	upgrade(boolean offline) Starts or continues the upgrade phase of a schema upgrade.

Methods inherited from class java.lang.Object

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

Constructor Detail

UpgradeDriver

public UpgradeDriver(DataSource dataSource,
                     InputStream upgradeScript,
                     AttributeValue[] defaultProperties)
              throws IfsException

Constructs an UpgradeDriver.

Default properties can be specified. These will be merged with the default properties in the upgrade script, overriding any like-named default properties there.

Parameters:

dataSource - a DataSource for the repository's schema

upgradeScript - the XML upgrade script

defaultProperties - additional default properties, or null if none

Throws:

IfsException - if the operation fails

(Unpublished)

Method Detail

addUpgradeDriverListener

public void addUpgradeDriverListener(UpgradeDriverListener udl)
                              throws IfsException

Adds an UpgradeDriverListener.

Specified by:

addUpgradeDriverListener in interface UpgradeDriverManager

Parameters:

udl - the listener

Throws:

IfsException - if the operation fails

removeUpgradeDriverListener

public void removeUpgradeDriverListener(UpgradeDriverListener udl)
                                 throws IfsException

Removes an UpgradeDriverListener.

Specified by:

removeUpgradeDriverListener in interface UpgradeDriverManager

Parameters:

udl - the listener

Throws:

IfsException - if the operation fails

analyze

public boolean analyze()
                throws IfsException

Starts or continues the analysis phase of a schema upgrade.

An exception is thrown if analyze, preUpgrade, upgrade, postUpgrade, or rollback are underway in another thread.

When the method is called, the upgrade status must be Initialized or Analyzing. Otherwise an exception is thrown.

If the analyze method of an upgrade action in the schema upgrade throws an exception, it is logged and rethrown. The upgrade status is set to Analyzing.

The method returns when the analysis phase is completed or stopped. If the analysis phase completes with no errors, the upgrade status is set to Analyzed and true is returned; otherwise the upgrade status is set to Analyzing and false is returned.

Specified by:

analyze in interface UpgradeDriverManager

Returns:

whether the analysis phase completed with no errors

Throws:

IfsException - if the operation fails

preUpgrade

public boolean preUpgrade()
                   throws IfsException

Starts, continues, or repeats the pre-upgrade phase of a schema upgrade.

An exception is thrown if analyze, preUpgrade, upgrade, postUpgrade, or rollback are underway in another thread.

When the method is called, the upgrade status must be Analyzed, Pre-upgrading, or Pre-upgraded. Otherwise an exception is thrown.

If the preUpgrade method of an upgrade action in the schema upgrade throws an exception, it is logged and rethrown. The upgrade status is set to Pre-upgrading.

The method returns when the pre-upgrade phase is completed or stopped. If the pre-upgrade phase completes with no errors, the upgrade status is set to Pre-upgraded and true is returned; otherwise the upgrade status is set to Pre-upgrading and false is returned.

Specified by:

preUpgrade in interface UpgradeDriverManager

Returns:

whether the pre-upgrade phase completed with no errors

Throws:

IfsException - if the operation fails

upgrade

public boolean upgrade(boolean offline)
                throws IfsException

Starts or continues the upgrade phase of a schema upgrade.

An exception is thrown if analyze, preUpgrade, upgrade, postUpgrade, or rollback are underway in another thread.

When the method is called, the upgrade status must be Pre-upgraded or Upgrading. Otherwise an exception is thrown.

The upgrade phase must be performed with the repository offline (that is, with all nodes stopped). If the repository is not offline, as indicated by the offline argument, an exception is thrown.

If the upgrade method of an upgrade action in the schema upgrade throws an exception, it is logged and rethrown. The upgrade status is set to Upgrading.

The method returns when the upgrade phase is completed or stopped. If the upgrade phase completes with no errors, the upgrade status is set to Upgraded, the schema version is updated to the target schema version, and true is returned; otherwise the upgrade status is set to Upgrading and false is returned.

Specified by:

upgrade in interface UpgradeDriverManager

Parameters:

offline - whether the repository is offline (that is, whether all nodes are stopped)

Returns:

whether the upgrade phase completed with no errors

Throws:

IfsException - if the operation fails

postUpgrade

public boolean postUpgrade()
                    throws IfsException

Starts or continues the post-upgrade phase of a schema upgrade.

An exception is thrown if analyze, preUpgrade, upgrade, postUpgrade, or rollback are underway in another thread.

When the method is called, the upgrade status must be Upgraded or Post-upgrading. Otherwise an exception is thrown.

If the postUpgrade method of an upgrade action in the schema upgrade throws an exception, it is logged and rethrown. The upgrade status is set to Post-upgrading.

The method returns when the post-upgrade phase is completed or stopped. If the post-upgrade phase completes with no errors, the upgrade status is set to Completed and true is returned; otherwise the upgrade status is set to Post-upgrading and false is returned.

Specified by:

postUpgrade in interface UpgradeDriverManager

Returns:

whether the post-upgrade phase completed with no errors

Throws:

IfsException - if the operation fails

rollback

public boolean rollback(boolean offline)
                 throws IfsException

Starts or continues rolling back a schema upgrade.

An exception is thrown if analyze, preUpgrade, upgrade, postUpgrade, or rollback are underway in another thread.

When the method is called, the upgrade status must be Initialized, Analyzing, Analyzed, Pre-upgrading, Pre-upgraded, Upgrading, Upgraded, Post-upgrading, Completed, or Rolling-back. Otherwise an exception is thrown.

If the upgrade status is Upgrading, Upgraded, Post-upgrading, or Completed, the rollback must be performed with the repository offline (that is, with all nodes stopped). If the repository is not offline, as indicated by the offline argument, an exception is thrown.

If the rollback method of an upgrade action in the schema upgrade throws an exception, it is logged and rethrown. The upgrade status is set to Rolling-back.

The method returns when the rollback is completed or stopped. If the rollback completes with no errors, the upgrade status is set to Rolled-back, the schema version is updated to the source schema version, and true is returned; otherwise the upgrade status is set to Rolling-back and false is returned.

Specified by:

rollback in interface UpgradeDriverManager

Parameters:

offline - whether the repository is offline (that is, whether all nodes are stopped)

Returns:

whether the rollback completed with no errors

Throws:

IfsException - if the operation fails

getCurrentTask

public int getCurrentTask()
                   throws IfsException

Gets the current task being performed by the upgrade driver.

The returned value is one of:

• TASK_NONE if no task is being performed,
• TASK_ANALYZE if executing the analyze method,
• TASK_PREUPGRADE if executing the preUpgrade method,
• TASK_UPGRADE if executing the upgrade method,
• TASK_POSTUPGRADE if executing the postUpgrade method, or
• TASK_ROLLBACK if executing the rollback method

Specified by:

getCurrentTask in interface UpgradeDriverManager

Returns:

the current task

Throws:

IfsException - if the operation fails

stop

public void stop()
          throws IfsException

Requests the in-progress analyze, preUpgrade, upgrade, postUpgrade, or rollback to stop.

If none of these methods are underway, a call to stop has no effect.

Specified by:

stop in interface UpgradeDriverManager

Throws:

IfsException

dispose

public void dispose()
             throws IfsException

Disposes this UpgradeDriverManager.

After this method is called, all other methods on this interface (apart from isDisposed, but including dispose) will throw an exception.

Specified by:

dispose in interface UpgradeDriverManager

Throws:

IfsException - if the operation fails

isDisposed

public boolean isDisposed()
                   throws IfsException

Gets whether dispose has been called on this UpgradeDriverManager.

Specified by:

isDisposed in interface UpgradeDriverManager

Returns:

whether disposed

Throws:

IfsException - if the operation fails

getUpgradeHistory

public UpgradeStatus[] getUpgradeHistory()
                                  throws IfsException

Gets the history of all schema upgrades performed or attempted, in chronological order.

Specified by:

getUpgradeHistory in interface UpgradeDriverManager

Returns:

the schema upgrades

Throws:

IfsException - if the operation fails

getMostRecentUpgrade

public UpgradeStatus getMostRecentUpgrade()
                                   throws IfsException

Gets the most-recent schema upgrade performed or attempted.

If an schema upgrade is underway, this method will return that upgrade.

Specified by:

getMostRecentUpgrade in interface UpgradeDriverManager

Returns:

the most-recent schema upgrade, or null if there is no previous schema upgrade

Throws:

IfsException - if the operation fails

toTaskLabel

public String toTaskLabel(int task)

Gets a string representation of the specified task value.

Specified by:

toTaskLabel in interface UpgradeDriverManager

Parameters:

task - the task; must be

• TASK_NONE,
• TASK_ANALYZE,
• TASK_PREUPGRADE,
• TASK_UPGRADE,
• TASK_POSTUPGRADE, or
• TASK_ROLLBACK

Returns:

a string representation

toStatusLabel

public String toStatusLabel(int status)

Gets a string representation of the specified status value.

Specified by:

toStatusLabel in interface UpgradeDriverManager

Parameters:

status - the status value; must be

• STATUS_INITIALIZED,
• STATUS_ANALYZING,
• STATUS_ANALYZED,
• STATUS_PREUPGRADING,
• STATUS_PREUPGRADED,
• STATUS_UPGRADING,
• STATUS_UPGRADED,
• STATUS_POSTUPGRADING,
• STATUS_COMPLETED,
• STATUS_ROLLINGBACK, or
• STATUS_ROLLEDBACK

Returns:

a string representation

acquireLock

protected Connection acquireLock()
                          throws IfsException

Acquires the exclusive right for the calling thread to access this UpgradeDriver's state and use its JDBC connection.

The calling thread must call releaseLock() to release the lock.

Returns:

the JDBC connection

Throws:

IfsException - if the operation fails

(Unpublished)

releaseLock

protected void releaseLock()
                    throws IfsException

Releases the exclusive right for the calling thread to access this UpgradeDriver's state and use its JDBC connection.

Throws:

IfsException - if the operation fails

(Unpublished)

getPreparedStatement

protected PreparedStatement getPreparedStatement(String sql)
                                          throws IfsException

Gets a PreparedStatement for the specified SQL.

If a PreparedStatement was previously created for the SQL, it is returned. Otherwise a new PreparedStatement is created and returned.

The caller should not close the returned PreparedStatement.

Parameters:

sql - the SQL

Returns:

a PreparedStatement for the SQL

Throws:

IfsException - if the operation fails

(Unpublished)

rollbackTransaction

protected static void rollbackTransaction(Connection conn)

Rolls-back the specified connection's transaction, best efforts.

Parameters:

conn - the connection

(Unpublished)

getUpgradeSequenceNextValue

protected long getUpgradeSequenceNextValue()
                                    throws IfsException

Returns the next value from the database sequence used for upgrades.

Returns:

the next sequence value

Throws:

IfsException - if the operation fails

(Unpublished)