org.jsimpledb.annotation

Annotation Type OnVersionChange

@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, the old value will always 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.

Optional Element Summary

Optional Elements

Modifier and Type	Optional Element and Description
int	newVersion Required new schema version.
int	oldVersion Required old schema version.

Element Detail

oldVersion

public abstract int oldVersion

Required old schema version.

If this property is set to a positive value, only version changes for which the previous schema version equals the specified version will result in notification, and the annotated method must have the corresponding parameter omitted. Otherwise notifications are delivered for any previous schema version and the oldVersion method parameter is required.

Negative values are not allowed.

Returns:

old schema version, or zero for no restriction

Default:

0

newVersion

public abstract int newVersion

Required new schema version.

If this property is set to a positive value, only version changes for which the new schema version equals the specified version will result in notification, and the annotated method must have the corresponding parameter omitted. Otherwise notifications are delivered for any new schema version and the newVersion method parameter is required.

Negative values are not allowed.

Returns:

new schema version, or zero for no restriction

Default:

0