Optimistic Locking With Version Number Using the AWS SDK for Java Object Persistence Model

The optimistic locking support in the Object Persistence model ensures that the client-side item that you are updating (or deleting) is the same as the item on the server-side. The version mismatch can happen if after you retrieve an item some other transaction updates that item on the server making your copy a stale version. Without optimistic locking, if you send an update request using your stale version, updates made by another request might be lost.

The Object Persistence model provides the @DynamoDBVersionAttribute annotation type that you can use to enable optimistic locking. To enable locking, you specify one class property to store version numbers and mark it using this annotation type. When you save an object, the corresponding item on the server will have an attribute that stores the version number. The DynamoDBMapper assigns a version number when you first save the object and increments the version number each time you update the item. Your update or delete request succeeds only if the client-side object version matches the corresponding version number of the item on the server-side.

For example, the following Java code snippet defines a CatalogItem class that has several properties. It also includes a property, Version, that is tagged with the @DynamoDBVersionAttribute annotation type.

@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {
    
    private Integer id;
    private String title;
    private String ISBN;
    private List<String> bookAuthors;
    private Long version;

    @DynamoDBHashKey(attributeName="Id")  
    public Integer getId() { return id; }
    public void setId(Integer Id) { this.id = Id; }
    
    @DynamoDBAttribute(attributeName="Title")  
    public String getTitle() { return title; }    
    public void setTitle(String title) { this.title = title; }
    
    @DynamoDBAttribute(attributeName="ISBN")  
    public String getISBN() { return ISBN; }    
    public void setISBN(String ISBN) { this.ISBN = ISBN;}
    
    @DynamoDBAttribute(attributeName = "Authors")
    public List<String> getBookAuthors() { return bookAuthors; }    
    public void setBookAuthors(List<String> bookAuthors) { this.bookAuthors = bookAuthors; }
    
    @DynamoDBVersionAttribute
    public Long getVersion() { return version; }
    public void setVersion(Long version) { this.version = version;}
}

You can apply the @DynamoDBVersion annotation to nullable types provided by the primitive wrappers classes such as Long and Integer, or you can use the primitive types int and long. We recommend that you use Integer and Long whenever possible.

Optimistic locking has the following impact on the typical CRUD operations:

DynamoDBMapper mapper = new DynamoDBMapper(client);
// Load a catalog item.

CatalogItem item = context.load(CatalogItem.class, 101);
item.setSomeProp("value");
...
// Save the item.
mapper.save(item, 
    new DynamoDBMapperConfig(
        DynamoDBMapperConfig.SaveBehavior.CLOBBER));