# Java 1.x：DynamoDBMapper
<a name="DynamoDBMapper"></a>

**注意**  
SDK for Java 有两个版本：1.x 和 2.x。我们已于 2024 年 1 月 12 日[宣布](https://aws.amazon.com/blogs/developer/announcing-end-of-support-for-aws-sdk-for-java-v1-x-on-december-31-2025/)终止支持 1.x 版本，并且将于 2025 年 12 月 31 日终止支持该版本。为进行新开发，强烈建议您使用 2.x。

适用于 Java 的 AWS SDK 提供了 `DynamoDBMapper` 类，使您能够将客户端类映射到 Amazon DynamoDB 表。要使用 `DynamoDBMapper`，您应在代码中定义 DynamoDB 表中项目与其相应对象实例之间的关系。`DynamoDBMapper` 类让您能够对项目执行各种创建、读取、更新和删除 (CRUD) 操作，并对表运行查询和扫描。

**Topics**
+ [DynamoDBMapper 类](DynamoDBMapper.Methods.md)
+ [DynamoDBMapper for Java 支持的数据类型](DynamoDBMapper.DataTypes.md)
+ [适用于 DynamoDB 的 Java 注释](DynamoDBMapper.Annotations.md)
+ [DynamoDBMapper 的可选配置设置](DynamoDBMapper.OptionalConfig.md)
+ [DynamoDB 和乐观锁（使用版本号）](DynamoDBMapper.OptimisticLocking.md)
+ [在 DynamoDB 中映射任意数据](DynamoDBMapper.ArbitraryDataMapping.md)
+ [DynamoDBMapper 示例](DynamoDBMapper.Examples.md)

**注意**  
`DynamoDBMapper` 类不允许创建、更新或删除表。要执行这些任务，请改用低级别 SDK for Java 接口。

SDK for Java 提供了一组注释类型，可用于将类映射到表。例如，我们来看一个使用 `ProductCatalog` 作为分区键的 `Id` 表。

```
ProductCatalog(Id, ...)
```

您可以将客户端应用程序中的类映射到 `ProductCatalog` 表（如下面的 Java 代码所示）。该代码定义了一个名为 `CatalogItem` 的普通旧 Java 对象 (POJO)，此对象使用注释将对象字段映射到 DynamoDB 属性名称。

**Example**  

```
package com.amazonaws.codesamples;

import java.util.Set;

import software.amazon.dynamodb.datamodeling.DynamoDBAttribute;
import software.amazon.dynamodb.datamodeling.DynamoDBHashKey;
import software.amazon.dynamodb.datamodeling.DynamoDBIgnore;
import software.amazon.dynamodb.datamodeling.DynamoDBTable;

@DynamoDBTable(tableName="ProductCatalog")
public class CatalogItem {

    private Integer id;
    private String title;
    private String ISBN;
    private Set<String> bookAuthors;
    private String someProp;

    @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 Set<String> getBookAuthors() { return bookAuthors; }
    public void setBookAuthors(Set<String> bookAuthors) { this.bookAuthors = bookAuthors; }

    @DynamoDBIgnore
    public String getSomeProp() { return someProp; }
    public void setSomeProp(String someProp) { this.someProp = someProp; }
}
```

在上述代码中，`@DynamoDBTable` 注释将 `CatalogItem` 类映射到 `ProductCatalog` 表。您可以将各个类实例存储为表中的项目。在类定义中，`@DynamoDBHashKey` 注释将 `Id` 属性映射到主键。

默认情况下，类属性会映射到表中的同名属性。`Title` 和 `ISBN` 属性会映射到表中的同名属性。

当 DynamoDB 属性的名称与类中声明的属性的名称匹配时，`@DynamoDBAttribute` 注释是可选的。当这两个名称不同时，请将此注释与 `attributeName` 参数一起使用以指定此属性对应的 DynamoDB 属性。

在上述示例中，`@DynamoDBAttribute` 注释将添加到每个属性中以确保属性名称与上一步骤中创建的表完全匹配，并且与本指南中其他代码示例中使用的属性名称保持一致。

您的类定义的某些属性可以不用映射到表中的任何属性。您可以通过添加 `@DynamoDBIgnore` 注释来识别这些属性。在上述示例中，`SomeProp` 属性是使用 `@DynamoDBIgnore` 注释标记的。在将 `CatalogItem` 实例上传到该表时，您的 `DynamoDBMapper` 实例不包含 `SomeProp` 属性。另外，映射器也不会在您检索表中的项目时返回此属性。

在定义了映射类之后，可以使用 `DynamoDBMapper` 方法将该类的实例写入 `Catalog` 表的对应项目。以下代码示例展示了这一技术。

```
AmazonDynamoDB client = AmazonDynamoDBClientBuilder.standard().build();

DynamoDBMapper mapper = new DynamoDBMapper(client);

CatalogItem item = new CatalogItem();
item.setId(102);
item.setTitle("Book 102 Title");
item.setISBN("222-2222222222");
item.setBookAuthors(new HashSet<String>(Arrays.asList("Author 1", "Author 2")));
item.setSomeProp("Test");

mapper.save(item);
```

以下代码示例说明如何检索该项目并访问它的某些属性。

```
CatalogItem partitionKey = new CatalogItem();

partitionKey.setId(102);
DynamoDBQueryExpression<CatalogItem> queryExpression = new DynamoDBQueryExpression<CatalogItem>()
    .withHashKeyValues(partitionKey);

List<CatalogItem> itemList = mapper.query(CatalogItem.class, queryExpression);

for (int i = 0; i < itemList.size(); i++) {
    System.out.println(itemList.get(i).getTitle());
    System.out.println(itemList.get(i).getBookAuthors());
}
```

`DynamoDBMapper` 提供了在 Java 内使用 DynamoDB 数据的一种直观而自然的方式。它还提供了一些内置功能，如乐观锁、ACID 事务、自动生成的分区键和排序键值以及对象版本控制。