com.amazon.carbonado

Annotation Type Version

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

Designates a Storable property as being the authoritative version number for the entire Storable instance. Only one property can have this designation.

Philosophically, a version property can be considered part of the identity of the storable. Unless the version is Derived, the repository is responsible for establishing the version on insert, and for auto-incrementing it on update. Under no circumstances should a normal version property be incremented manually; this can result in a false OptimisticLockException, or worse may allow the persistent record to become corrupted.

When updating a storable which has a normal version property, a value for the version must be specified along with its primary key. Otherwise, an IllegalStateException is thrown when calling update. If the update operation detects that the specified version doesn't exactly match the version of the existing persisted storable, an OptimisticLockException is thrown. For Derived versions, an OptimisticLockException is thrown only if the update detects that the new version hasn't incremented.

The actual type of the version property can be anything, but some repositories might only support integers. For maximum portability, version properties should be a regular 32-bit int.

Example:

 public interface UserInfo extends Storable {
     @Version
     int getRecordVersionNumber();
     void setRecordVersionNumber(int version);

     ...
 }
 

Author:

Brian S O'Neill, Don Schneider

See Also:

OptimisticLockException