# 适用于 DynamoDB 的 Java 注释
此部分介绍可用于将类和属性映射到 Amazon DynamoDB 中表和属性的注释。
有关相应的 Javadoc 文档，请参阅[适用于 Java 的 AWS SDKAPI 参考](https://docs.aws.amazon.com/sdk-for-java/latest/reference/)的[注释类型汇总](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/package-summary.html)。
**注意**
在以下注释中，只有 `DynamoDBTable` 和 `DynamoDBHashKey` 是必需的。
**Topics**
+ [DynamoDBAttribute](#DynamoDBMapper.Annotations.DynamoDBAttribute)
+ [DynamoDBAutoGeneratedKey](#DynamoDBMapper.Annotations.DynamoDBAutoGeneratedKey)
+ [DynamoDBAutoGeneratedTimestamp](#DynamoDBMapper.Annotations.DynamoDBAutoGeneratedTimestamp)
+ [DynamoDBDocument](#DynamoDBMapper.Annotations.DynamoDBDocument)
+ [DynamoDBHashKey](#DynamoDBMapper.Annotations.DynamoDBHashKey)
+ [DynamoDBIgnore](#DynamoDBMapper.Annotations.DynamoDBIgnore)
+ [DynamoDBIndexHashKey](#DynamoDBMapper.Annotations.DynamoDBIndexHashKey)
+ [DynamoDBIndexRangeKey](#DynamoDBMapper.Annotations.DynamoDBIndexRangeKey)
+ [DynamoDBRangeKey](#DynamoDBMapper.Annotations.DynamoDBRangeKey)
+ [DynamoDBTable](#DynamoDBMapper.Annotations.DynamoDBTable)
+ [DynamoDBTypeConverted](#DynamoDBMapper.Annotations.DynamoDBTypeConverted)
+ [DynamoDBTyped](#DynamoDBMapper.Annotations.DynamoDBTyped)
+ [DynamoDBVersionAttribute](#DynamoDBMapper.Annotations.DynamoDBVersionAttribute)
## DynamoDBAttribute
将属性映射到表属性。默认情况下，每个类属性都会映射到具有同名的项目属性。但是，如果名称不同，您可以使用此注释将某一属性映射到表属性。在以下 Java 代码段中，`DynamoDBAttribute` 将 `BookAuthors` 属性映射到表中的 `Authors` 属性名。
```
@DynamoDBAttribute(attributeName = "Authors")
public List getBookAuthors() { return BookAuthors; }
public void setBookAuthors(List BookAuthors) { this.BookAuthors = BookAuthors; }
```
`DynamoDBMapper` 在向表中保存对象时将 `Authors` 用作属性名称。
## DynamoDBAutoGeneratedKey
将分区键或排序键属性标记为自动生成。保存这些属性时，`DynamoDBMapper` 将生成随机 [UUID](http://docs.oracle.com/javase/6/docs/api/java/util/UUID.html)。只有字符串属性可被标记为自动生成键。
以下示例演示如何使用自动生成键。
```
@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());
}
}
```
## DynamoDBAutoGeneratedTimestamp
自动生成时间戳。
```
@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"
}
}
```
## DynamoDBHashKey
将类属性映射到表的分区键。属性必须是标量字符串、数字或二进制类型。属性不能是集合类型。
假定您有一个 `ProductCatalog` 表，这个表使用 `Id` 作为主键。以下 Java 代码示例定义了一个 `CatalogItem` 类，并使用 `Id` 标签将其 `ProductCatalog` 属性映射到 `@DynamoDBHashKey` 表的主键。
```
@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。
## DynamoDBIndexHashKey
将类属性映射到全局二级属性的分区键。属性必须是标量字符串、数字或二进制类型。属性不能是集合类型。
如果您需要 `Query` 到全局二级索引，使用此注释。必须指定索引名称 (`globalSecondaryIndexName`)。如果类属性的名称不同于索引分区键，则您还必须指定该索引属性的名称 (`attributeName`)。
## DynamoDBIndexRangeKey
将类属性映射到全局二级索引或本地二级索引的排序键。属性必须是标量字符串、数字或二进制类型。属性不能是集合类型。
如果您需要对本地二级索引或全局二级索引执行 `Query` 操作，并使用索引排序键细化结果，请使用此注释。必须指定索引名称 (`globalSecondaryIndexName` 或 `localSecondaryIndexName`)。如果类属性的名称不同于索引排序键，则您还必须指定该索引属性的名称 (`attributeName`)。
## DynamoDBRangeKey
将类属性映射到表的排序键。属性必须是标量字符串、数字或二进制类型。它不能是集合类型。
如果主键是复合键 (分区键和排序键)，您可以使用此标签将您的类字段映射到排序键。例如，假定您的 `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 { ...}
```
## DynamoDBTypeConverted
用于将属性标记为使用自定义类型转换器的注释。可以在用户定义的注释上进行注释以将更多属性传递到 `DynamoDBTypeConverter`。
`DynamoDBTypeConverter` 接口可让您将自己的任意数据类型映射到受 DynamoDB 原生支持的数据类型。有关更多信息，请参阅 [在 DynamoDB 中映射任意数据](DynamoDBMapper.ArbitraryDataMapping.md)。
## DynamoDBTyped
用于覆盖标准属性类型绑定的注释。如果应用了针对标准类型的默认属性绑定，则该类型不需要该注释。
## DynamoDBVersionAttribute
确定一个类属性以存储乐观锁版本号。`DynamoDBMapper` 会在保存新项目时为此属性分配版本号，并且会在您每次更新该项目时增加版本号的值。仅支持数字标量类型。有关数据类型的更多信息，请参阅 [数据类型](HowItWorks.NamingRulesDataTypes.md#HowItWorks.DataTypes)。有关版本控制的更多信息，请参阅[DynamoDB 和乐观锁（使用版本号）](DynamoDBMapper.OptimisticLocking.md)。