@Retention(value=RUNTIME)
@Target(value=METHOD)
@Documented
public @interface OnVersionChange

Annotation for methods that are to be invoked whenever an object's schema version has just changed.

Method Parameters

The annotated method must be an instance method (i.e., not static), return void, and take one, two, or all three of the following parameters in order:

1. int oldVersion - previous schema version; should be present only if oldVersion() is zero
2. int newVersion - new schema version; should be present only if newVersion() is zero
3. Map<Integer, Object> oldValues or Map<String, Object> oldValues - immutable map containing all field values from the previous version of the object, indexed by either storage ID or field name.

If a class has multiple @OnVersionChange-annotated methods, methods with more specific constraint(s) (i.e., non-zero oldVersion() and/or newVersion()) will be invoked first.

Incompatible Schema Changes

JSimpleDB supports arbitrary Java model schema changes across schema versions, including adding and removing Java types. As a result, it's possible for the previous version of an object to contain reference fields whose Java types no longer exist in the current Java model. Specifically, this can happen in two ways:

• A reference field refers to an object type that no longer exists; or
• An Enum field refers to an Enum type that no longer exists, or whose constants have changed

In these cases, the old field's value cannot be represented in oldValues using the original Java types. Instead, more generic types are used:

• For a reference field whose type no longer exists, the referenced object will be an UntypedJObject. Note that the fields in the UntypedJObject may still be accessed by invoking the JTransaction field access methods with upgradeVersion set to false (otherwise, a TypeNotInSchemaVersionException is thrown).
• For Enum fields whose type no longer exists or has modified constants, the old value will be represented as an EnumValue object.

In addition to Java types disappearing, it's also possible that the type of a reference field is narrower in the current Java code than it was in the previous Java code. If an object held a reference in such a field to another object outside the new, narrower type, then upgrading the object without change would represent a violation of Java type safety. Therefore, when any object is upgraded, all references that would otherwise be illegal are cleared (in the manner of DeleteAction.UNREFERENCE); use oldValues to access the previous field value(s) if needed.