AO 0.18.x upgrade guide

First of all, thank you for all of your help, your testing, and your feedback over the last several months. Because you have been willing to give the Developer Preview of AO a try, we're going to be able to provide a rock-solid data storage layer in the Atlassian Platform.

As you and we have continued to push this new technology forward, we've discovered some limitations in the way the underlying Java.net AO library was implemented. It didn't take as much care as needed to ensure that your data was 100% compatible with all of our supported database, or that we could move data from one database to another (i.e, through a backup/restore) with complete safety. Your bug reports and our testing helped uncover those problems.

Even though it's late in the development process, these kinds of bugs are serious. So we set out to eliminate them before we declare AO a stable part of the Atlassian Platform. We undertook a significant refactoring of the AO library two weeks ago. The first thing we did was increase the AO library's test suite by 400%, focusing especially on data type mappings, import/export, and migrations. That showed us some gaps, and we've spent the the time since slowly eliminating those gaps. These changes we made will necessitate some refactoring of your plugins, and that's what this guide is about. We understand that this will cause some additional work for you late in your dev process, and for that we apologize. However, in the long term, we believe these changes will significantly reduce the number of support problems for customers, so we can all spend more time building value and less time handling support.

Type Changes

In order to ensure that your data will work no matter what database the user might have, we have limited AO to supported a certain list of SQL types. As such, if you're using a type not on the list below, you will need to refactor.

Also note that the table below denotes which types can be used as primary keys. An error will be thrown if you try to use an invalid primary key type.

Notes referred to in the table above

More notes

• Enums used to be Integers but are now Strings.
• Clobs are now defined via the @StringLength annotation.

Removed Types

Added @StringLength

This annotation can be used to override the default maximum string length for String, URL, URI, and Enum fields.

This is also the mechanism used to switch between VARCHAR and CLOB.

examples:

Not Annotated = VARCHAR(255)
@StringLength(500) = VARCHAR(500)
@StringLength(StringLength.UNLIMITED) = CLOB

Note that you cannot set a specific maximum length that is greater than 767. That is the greatest length that is always allowed for VARCHARs in all the supported databases (specifically, this limit is from MySQL).

Removed Database Functions as @Default values

AO used to let you specify a databse function as the value for the @Default annotation. This was to enable using CURRENT_DATE as a default value.

Due to the fact that database functions are implemented differently (if at all) and the fact that DATETIME does not support functions in most databases, we have removed support for this.

You can still use a string literal as a default value. e.g., @Default("2011-11-11 12:34:56")

Removed @OnUpdate annotation

This annotation was used to set a value on a column everytime the entity was updated.

Essentially, the only thing that this was used for was to auto-update a timestamp field.

Since we no longer support database functions we removed this feature.

New Reserved Words

In this new version, certain Oracle reserved keywords are no longer available to use for your table and column names. This applies to any database you're working against as obviously we(you) need to support all databases.

The reserved words are BLOB, CLOB, NUMBER, ROWID, TIMESTAMP, VARCHAR2.

The reason for doing this is that in order to support auto-increment IDs in Oracle we need to use triggers. Oracle has issues with triggers containing table or column names that also are keywords in some cases.

Note, this shouldn't affect your table names since AO prefixes table names of each plugin like this: AO_XXXXXX_, but it could affect your column names. So if you have columns named with one of those six words, you'll need to refactor.

We don't think these six words are likely to have been used, but if you find that you're affected by this change, please contact us and we'll try to find you a smooth transition.

New Column Name Length Restriction

No database column name can have a length over 30 characters (the maximum length supported by Oracle). The AO plugin will validate table and column names at startup, when the AO module is first loaded.

Removed @SQLType

The AO type system has gone through a major refactoring and now has a one-to-one mapping between Java and Database Types.

Due to this, we have removed the @SQLType annotation completely.

Type system is now immutable

Previously, the type system was mutable and allowed plugins to add new type mappings. The new type system is immutable and plugins can no longer add types.

If you were relying on this "feature", you need to do some refactoring an only use the built-in supported types.

Removed Test name converters in version 0.18.5

From version 0.18.5, the test name converters are no longer available. The AO lib uses the correct strategy by default so no need to set any name converters when testing anymore.