適用於 DynamoDB 的 Java 註釋

本節說明可用於將類別和屬性映射至 Amazon DynamoDB 中資料表和屬性的註釋。

如需對應的 Javadoc 文件，請參閱《AWS SDK for Java API 參考》中的註釋類型摘要。

注意

在下列註釋中，只需要 DynamoDBTable 和 DynamoDBHashKey。

DynamoDBAttribute

將屬性映射至資料表屬性。每個類別屬性預設會映射至同名的項目屬性。不過，如果名稱不同，您可以使用此註釋將屬性 (property) 映射至屬性 (attribute)。在下列 Java 程式碼片段中，DynamoDBAttribute 會將 BookAuthors 屬性映射至資料表中的 Authors 屬性名稱。

@DynamoDBAttribute(attributeName = "Authors")
public List<String> getBookAuthors() { return BookAuthors; }
public void setBookAuthors(List<String> BookAuthors) { this.BookAuthors = BookAuthors; }

將物件儲存至資料表時，DynamoDBMapper 使用 Authors 做為屬性名稱。

DynamoDB AutoGeneratedKey

將分割區索引鍵或排序索引鍵屬性標示為自動產生。儲存這些屬性時，DynamoDBMapper​ 會產生隨機 ​UUID。只有字串屬性才能標示為自動產生的索引鍵。

以下是示範使用自動產生索引鍵參數的範例。

@DynamoDBTable(tableName="AutoGeneratedKeysExample")
public class AutoGeneratedKeys {
    private String id;
    private String payload;

    @DynamoDBHashKey(attributeName = "Id")
    @DynamoDBAutoGeneratedKey
    public String getId() { return id; }
    public void setId(String id) { this.id = id; }

    @DynamoDBAttribute(attributeName="payload")
    public String getPayload() { return this.payload; }
    public void setPayload(String payload) { this.payload = payload; }

    public static void saveItem() {
        AutoGeneratedKeys obj = new AutoGeneratedKeys();
        obj.setPayload("abc123");

        // id field is null at this point
        DynamoDBMapper mapper = new DynamoDBMapper(dynamoDBClient);
        mapper.save(obj);

        System.out.println("Object was saved with id " + obj.getId());
    }
}

DynamoDB AutoGeneratedTimestamp

自動產生時間戳記。

@DynamoDBAutoGeneratedTimestamp(strategy=DynamoDBAutoGenerateStrategy.ALWAYS)
public Date getLastUpdatedDate() { return lastUpdatedDate; }
public void setLastUpdatedDate(Date lastUpdatedDate) { this.lastUpdatedDate = lastUpdatedDate; }

或者，可以透過提供策略屬性來定義自動產生策略。預設值為 ALWAYS。

DynamoDBDocument

指出類別可以序列化為 Amazon DynamoDB 文件。

例如，假設您要將 JSON 文件映射至 Map (M) 類型的 DynamoDB 屬性。下列程式碼範例定義包含 Map 類型之巢狀屬性 (Pictures) 的項目。

public class ProductCatalogItem {

    private Integer id;  //partition key
    private Pictures pictures;
    /* ...other attributes omitted... */

    @DynamoDBHashKey(attributeName="Id")
    public Integer getId() { return id;}
    public void setId(Integer id) {this.id = id;}

    @DynamoDBAttribute(attributeName="Pictures")
    public Pictures getPictures() { return pictures;}
    public void setPictures(Pictures pictures) {this.pictures = pictures;}

    // Additional properties go here.

    @DynamoDBDocument
    public static class Pictures {
        private String frontView;
        private String rearView;
        private String sideView;

        @DynamoDBAttribute(attributeName = "FrontView")
        public String getFrontView() { return frontView; }
        public void setFrontView(String frontView) { this.frontView = frontView; }

        @DynamoDBAttribute(attributeName = "RearView")
        public String getRearView() { return rearView; }
        public void setRearView(String rearView) { this.rearView = rearView; }

        @DynamoDBAttribute(attributeName = "SideView")
        public String getSideView() { return sideView; }
        public void setSideView(String sideView) { this.sideView = sideView; }

     }
}

然後您就可儲存新的 ProductCatalog 項目，並具有 Pictures，如下列範例所示。

ProductCatalogItem item = new ProductCatalogItem();

Pictures pix = new Pictures();
pix.setFrontView("http://example.com/products/123_front.jpg");
pix.setRearView("http://example.com/products/123_rear.jpg");
pix.setSideView("http://example.com/products/123_left_side.jpg");
item.setPictures(pix);

item.setId(123);

mapper.save(item); 

產生的 ProductCatalog項目看起來將會如下 (JSON 格式)。

{
  "Id" : 123
  "Pictures" : {
    "SideView" : "http://example.com/products/123_left_side.jpg",
    "RearView" : "http://example.com/products/123_rear.jpg",
    "FrontView" : "http://example.com/products/123_front.jpg"
  }
} 

DynamoDB HashKey

將類別屬性映射至資料表的分割區索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。此屬性不能是集合類型。

假設您的 ProductCatalog 資料表將 Id 作為主索引鍵。下列 Java 程式碼定義 CatalogItem 類別，並使用 @DynamoDBHashKey 標籤將其 Id 屬性映射至 ProductCatalog 資料表的主索引鍵。

@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {
    private Integer Id;
   @DynamoDBHashKey(attributeName="Id")
   public Integer getId() {
        return Id;
   }
   public void setId(Integer Id) {
        this.Id = Id;
   }
   // Additional properties go here.
}

DynamoDBIgnore

指出應該忽略相關聯屬性的 DynamoDBMapper 執行個體。將資料儲存至資料表時，DynamoDBMapper 不會將此屬性儲存至資料表。

套用至 getter 方法或非模組化屬性的類別欄位。若該註釋是直接套用至類別欄位，則必須在相同的類別宣告相對應的 getter 和 setter。

DynamoDB IndexHashKey

將類別屬性映射至全域次要索引的分割區索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。此屬性不能是集合類型。

如果您需要對全域次要索引進行 Query，請使用此註釋。您必須指定索引名稱 (globalSecondaryIndexName)。如果類別屬性的名稱與索引的分割區索引鍵不同，您也必須指定該索引屬性的名稱 (attributeName)。

DynamoDB IndexRangeKey

將類別屬性映射至全域次要索引或本機次要索引的排序索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。此屬性不能是集合類型。

如果您需要對本機次要索引或全域次要索引進行 Query，並且想要使用索引的排序索引鍵來縮小您結果的範圍，請使用此註釋。您必須指定索引名稱 (globalSecondaryIndexName 或 localSecondaryIndexName)。如果類別屬性的名稱與索引的排序索引鍵不同，您也必須指定該索引屬性的名稱 (attributeName)。

DynamoDB RangeKey

將類別屬性映射至資料表的排序索引鍵。此屬性必須是純量字串、數字或二進位類型的其中之一。它不能是集合類型。

如果主索引鍵是複合 (分割區索引鍵和排序索引鍵)，您可以使用此標籤，將類別欄位映射至排序索引鍵。例如，假設您的 Reply 資料表存放論壇主題回覆。每個對話都可以有許多回覆。因此，此資料表的主索引鍵是 ThreadId 和 ReplyDateTime。分割區索引鍵是 ThreadId，而排序索引鍵是 ReplyDateTime。

下列 Java 程式碼定義 Reply 類別，並將它映射至 Reply 資料表。它會使用 @DynamoDBHashKey 和 @DynamoDBRangeKey 標籤來識別映射至主索引鍵的類別屬性。

@DynamoDBTable(tableName="Reply")
public class Reply {
    private Integer id;
    private String replyDateTime;

    @DynamoDBHashKey(attributeName="Id")
    public Integer getId() { return id; }
    public void setId(Integer id) { this.id = id; }

    @DynamoDBRangeKey(attributeName="ReplyDateTime")
    public String getReplyDateTime() { return replyDateTime; }
    public void setReplyDateTime(String replyDateTime) { this.replyDateTime = replyDateTime; }

   // Additional properties go here.
}

DynamoDBTable

識別 DynamoDB 中的目標資料表。下列 Java 程式碼定義 Developer 類別，並將它映射至 DynamoDB 中的 People 資料表。

@DynamoDBTable(tableName="People")
public class Developer { ...} 

@DynamoDBTable 註釋可以予以繼承。任何繼承自 Developer 類別的新類別也會映射至 People 資料表。例如，假設您建立繼承自 Lead 類別的 Developer 類別。因為您已將 Developer 類別映射至 People 資料表，所以也會將 Lead 類別物件存放至相同的資料表。

@DynamoDBTable 也可以予以覆寫。任何繼承自 Developer 類別的新類別預設會映射至相同的 People 資料表。不過，您可以覆寫此預設映射。例如，如果您建立繼承自 Developer 類別的類別，則可以新增 @DynamoDBTable 註釋，明確地將它映射至另一個資料表，如下列 Java 程式碼範例所示。

@DynamoDBTable(tableName="Managers")
public class Manager extends Developer { ...} 

DynamoDB TypeConverted

將屬性標示為使用自訂類型轉換器的註釋。可以標註於使用者定義的註釋，以將其他屬性傳遞給 DynamoDBTypeConverter。

DynamoDBTypeConverter 界面可讓您將自己的任意資料類型映射至 DynamoDB 原生支援的資料類型。如需詳細資訊，請參閱 映射任意資料。

DynamoDBTyped

覆寫標準屬性類型繫結的註釋。如果套用標準類型的預設屬性繫結，則該類型不需要註釋。

DynamoDB VersionAttribute

識別用於存放樂觀鎖定版本編號的類別屬性。DynamoDBMapper​ 在儲存新的項目時會將版本編號指派給此屬性，並在每次您更新項目時予以遞增。僅支援數字純量類型。如需資料類型的詳細資訊，請參閱 資料類型。如需版本控制的詳細資訊，請參閱「含版本編號的樂觀鎖定」。