org.apache.derby.impl.sql.catalog
Class DD_Version

java.lang.Object
  org.apache.derby.impl.sql.catalog.DD_Version

All Implemented Interfaces:

java.io.Externalizable, Formatable, java.io.Serializable, TypedFormat

public class DD_Version

extends java.lang.Object

implements Formatable

Generic code for upgrading data dictionaries. Currently has all minor version upgrade logic.

A word about minor vs. major upgraded. Minor upgrades must be backwards/forwards compatible. So they cannot version classes or introduce new classes. Major releases are only backwards compatible; they will run against an old database, but not the other way around. So they can introduce new classes, etc.

Author:

Rick

See Also:

Serialized Form

Field Summary

private DataDictionaryImpl	bootingDictionary
(package private) int	majorVersionNumber
private int	minorVersionNumber

Constructor Summary

	DD_Version() Public niladic constructor needed for Formatable interface.
(package private)	DD_Version(DataDictionaryImpl bootingDictionary, int majorVersionNumber) Construct a Version for the currently booting data dictionary.

Method Summary

private void	applySafeChanges(TransactionController tc, int fromMajorVersionNumber, int lastSoftUpgradeVersion) Apply changes that can safely be made in soft upgrade.
(package private) boolean	checkVersion(int requiredMajorVersion, java.lang.String feature) Check to see if a database has been upgraded to the required level in order to use a language feature.
private void	doFullUpgrade(TransactionController tc, int fromMajorVersionNumber) Do full upgrade.
protected void	dropJDBCMetadataSPSes(TransactionController tc, boolean removeSYSIBMonly) Drop all jdbc metadata spses.
protected void	dropSystemCatalog(TransactionController tc, CatalogRowFactory crf) Drop a System catalog.
protected void	dropSystemCatalogDescription(TransactionController tc, TableDescriptor td) Remove the description of a System table from the data dictionary.
protected void	fillIndex(TransactionController tc, long heapConglomerateNumber, TabInfo tabInfo, int indexNumber) Populates a new system index from the base system table.
private int	getJBMSMinorVersionNumber() Get the minor version from the JBMS product minor version/maint version.
int	getTypeFormatId() Get the formatID which corresponds to this class.
private void	handleMinorRevisionChange(TransactionController tc, DD_Version fromVersion, boolean softUpgradeRun) Do any work needed for a minor revision change.
private static java.lang.String	majorToString(int majorVersionNumber)
protected void	makeSystemCatalog(TransactionController tc, TabInfo ti) Make a catalog.
void	readExternal(java.io.ObjectInput in) Read this object from a stream of stored objects.
java.lang.String	toString() Stringify this Version.
(package private) void	upgradeIfNeeded(DD_Version dictionaryVersion, TransactionController tc, java.util.Properties startParams) Upgrade the data dictionary catalogs to the version represented by this DD_Version.
void	writeExternal(java.io.ObjectOutput out) Write this object to a stream of stored objects.

Methods inherited from class java.lang.Object

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

Field Detail

bootingDictionary

private transient DataDictionaryImpl bootingDictionary

majorVersionNumber

int majorVersionNumber

minorVersionNumber

private int minorVersionNumber

Constructor Detail

DD_Version

public DD_Version()

Public niladic constructor needed for Formatable interface.

DD_Version

DD_Version(DataDictionaryImpl bootingDictionary,
           int majorVersionNumber)

Construct a Version for the currently booting data dictionary. The minor version is set by the subclass.

Parameters:

bootingDictionary - The booting dictionary that needs to be upgraded.

Method Detail

toString

public java.lang.String toString()

Stringify this Version.

Returns:

String representation of this Version.

majorToString

private static java.lang.String majorToString(int majorVersionNumber)

upgradeIfNeeded

void upgradeIfNeeded(DD_Version dictionaryVersion,
                     TransactionController tc,
                     java.util.Properties startParams)
               throws StandardException

Upgrade the data dictionary catalogs to the version represented by this DD_Version.

Parameters:

dictionaryVersion - the version of the data dictionary tables.

Throws:

StandardException - Ooops

applySafeChanges

private void applySafeChanges(TransactionController tc,
                              int fromMajorVersionNumber,
                              int lastSoftUpgradeVersion)
                       throws StandardException

Apply changes that can safely be made in soft upgrade. Any changes must not prevent the database from being re-booted by the a Derby engine at the older version fromMajorVersionNumber.
Examples are fixes to catalog meta data, e.g. fix nullability of a system column.
Upgrade items for 10.1

• None.

Parameters:

tc - transaction controller

fromMajorVersionNumber - version of the on-disk database

lastSoftUpgradeVersion - last engine to perform a soft upgrade that made changes.

Throws:

StandardException - Standard Cloudscape error policy.

doFullUpgrade

private void doFullUpgrade(TransactionController tc,
                           int fromMajorVersionNumber)
                    throws StandardException

Do full upgrade. Apply changes that can NOT be safely made in soft upgrade.
Upgrade items for 10.1

• None.

Parameters:

tc - transaction controller

fromMajorVersionNumber - version of the on-disk database

Throws:

StandardException - Standard Cloudscape error policy.

handleMinorRevisionChange

private void handleMinorRevisionChange(TransactionController tc,
                                       DD_Version fromVersion,
                                       boolean softUpgradeRun)
                                throws StandardException

Do any work needed for a minor revision change. For the data dictionary this is always invalidating stored prepared statements. When we are done with the upgrade, we always recompile all SPSes so the customer doesn't have to (and isn't going to get deadlocks because of the recomp).

Parameters:

tc - the xact

Throws:

StandardException - Standard Cloudscape error policy.

dropJDBCMetadataSPSes

protected void dropJDBCMetadataSPSes(TransactionController tc,
                                     boolean removeSYSIBMonly)
                              throws StandardException

Drop all jdbc metadata spses. This it to ensure that we don't have any problems with old metadata queries that have outdated query text (the plans are always cleared out on upgrade time).

Parameters:

tc - the xact

Throws:

StandardException - Standard Cloudscape error policy.

makeSystemCatalog

protected void makeSystemCatalog(TransactionController tc,
                                 TabInfo ti)
                          throws StandardException

Make a catalog.

Parameters:

tc - TransactionController

Throws:

StandardException - Standard Cloudscape error policy.

dropSystemCatalogDescription

protected void dropSystemCatalogDescription(TransactionController tc,
                                            TableDescriptor td)
                                     throws StandardException

Remove the description of a System table from the data dictionary. This does not delete the conglomerates that hold the catalog or its indexes.

Parameters:

tc - TransactionController

td - Table descriptor for the catalog to drop.

Throws:

StandardException - Standard Cloudscape error policy.

dropSystemCatalog

protected void dropSystemCatalog(TransactionController tc,
                                 CatalogRowFactory crf)
                          throws StandardException

Drop a System catalog.

Parameters:

tc - TransactionController

crf - CatalogRowFactory for the catalog to drop.

Throws:

StandardException - Standard Cloudscape error policy.

fillIndex

protected void fillIndex(TransactionController tc,
                         long heapConglomerateNumber,
                         TabInfo tabInfo,
                         int indexNumber)
                  throws StandardException

Populates a new system index from the base system table.

Parameters:

tc - transaction controller

heapConglomerateNumber - identifies system table to Store

tabInfo - describes base system table

indexNumber - index to populate

Throws:

StandardException - Thrown on failure

getTypeFormatId

public int getTypeFormatId()

Get the formatID which corresponds to this class. Map to the 5.0 version identifier so that 5.0 will understand this object when we write it out in soft upgrade mode. CS 5.0 will de-serialize it correctly. When we are writing out a 5.1 version number we write out the 5.1 version just to ensure no problems.

Specified by:

getTypeFormatId in interface TypedFormat

Returns:

the formatID of this class

readExternal

public final void readExternal(java.io.ObjectInput in)
                        throws java.io.IOException

Read this object from a stream of stored objects. Set the minor version. Ignore the major version.

Specified by:

readExternal in interface java.io.Externalizable

Parameters:

in - read this.

Throws:

java.io.IOException - on error

writeExternal

public final void writeExternal(java.io.ObjectOutput out)
                         throws java.io.IOException

Write this object to a stream of stored objects. Write out the minor version which is bumped across minor release. Just to be safe, write out the major version too. This will allow us to do versioning of a specific Version impl in the future.

Specified by:

writeExternal in interface java.io.Externalizable

Parameters:

out - write bytes here.

Throws:

java.io.IOException - on error

getJBMSMinorVersionNumber

private int getJBMSMinorVersionNumber()

Get the minor version from the JBMS product minor version/maint version. Bumps it up by 1 if production, or 0 if beta to ensure minor upgrade across beta. Starts at 2 because of an old convention. We use this starting at 2 to allow soft upgrade to write a version of 1 with the old major number to ensure a minor upgrade when reverting to an old version afer a soft upgrade. E.g run with 5.0.2, then 5.2.1.1, then 5.0.2. Want to ensure 5.0.2 does the minor upgrade.

Returns:

the minor version For 5.0 and 5.1 the minor number was calculated as jbmsVersion.getMinorVersion()*100 +jbmsVersion.getMaintVersion() + (jbmsVersion.isBeta() ? 0 : 1) + 2 5.0.22 => (0*100) + 22 + 2 = 24 - (5.0 has a unique major number) 5.1.2 => (1*100) + 2 + 2 = 104 - (5.1 has a unique major number) With the switch to the four part scheme in 5.2, the maint number now is in increments of one million, thus the above scheme could lead to duplicate numbers. Note that the major number may not change when the minor external release changes, e.g. 5.2 and 5.3 could share a DD_Version major number. 5.2.1.100 => (2*100) + 1000100 + 2 = 1000302 5.3.1.0 => (3*100) + 1000000 + 2 = 1000302

checkVersion

boolean checkVersion(int requiredMajorVersion,
                     java.lang.String feature)
               throws StandardException

Check to see if a database has been upgraded to the required level in order to use a language feature.

Parameters:

feature - Non-null to throw an error, null to return the state of the version match.

Returns:

True if the database has been upgraded to the required level, false otherwise.

Throws:

StandardException