# 使用适用于 RDS 数据 API 的 Java 客户端库
<a name="data-api.java-client-library"></a>

您可以下载并使用适用于 RDS 数据 API（数据 API）的 Java 客户端库。此 Java 客户端库提供了使用数据 API 的另一种方法。使用该库，您可以将客户端类映射到数据 API 的请求和响应。这种映射支持可以简化与某些特定 Java 类型（如 `Date`、`Time` 和 `BigDecimal`）的集成。

## 下载适用于 Data API 的 Java 客户端库
<a name="data-api.java-client-library.downloading"></a>

Data API Java 客户端库是 GitHub 中是开源的，位于以下位置：

[ https://github.com/awslabs/rds-data-api-client-library-java](https://github.com/awslabs/rds-data-api-client-library-java)

您可以从源文件手动构建该库，但最佳实践是使用 Apache Maven 依赖项管理来使用该库。将以下依赖项添加到 Maven POM 文件中。

 对于与 AWS SDK 2.x 兼容的版本 2.x，请使用以下命令：

```
<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>
```

 对于与 AWS SDK 1.x 兼容的版本 1.x，请使用以下命令：

```
<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>
```

## Java 客户端库示例
<a name="data-api.java-client-library.examples"></a>

在下面，您可以找到一些使用 Data API Java 客户端库的常见示例。这些示例假设您有一个包含两列（`accountId` 和 `name`）的表 `accounts`。您还拥有以下数据传输对象 (DTO)。

```
public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}
```

该客户端库使您可以将 DTO 作为输入参数进行传递。以下示例演示了如何将客户 DTO 映射到输入参数集。

```
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParamSets(account1, account2)
         .execute();
```

在某些情况下，使用简单值作为输入参数会更容易。可以使用以下语法来做到这一点。

```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParameter("accountId", 3)
         .withParameter("name", "Zhang")
         .execute();
```

下面是另一个使用简单值作为输入参数的示例。

```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
         .execute();
```

当返回结果时，客户端库提供到 DTO 的自动映射。以下示例演示了如何将结果映射到您的 DTO。

```
List<Account> result = client.forSql("SELECT * FROM accounts")
          .execute()
          .mapToList(Account.class);

Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
          .execute()
          .mapToSingle(Account.class);
```

在很多情况下，数据库结果集只包含一个值。为了简化检索此类结果的过程，客户端库提供了以下 API：

```
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);
```

**注意**  
`mapToList` 函数将 SQL 结果集转换为用户定义的对象列表。我们不支持在对 Java 客户端库的 `ExecuteStatement` 调用中使用 `.withFormatRecordsAs(RecordsFormatType.JSON)` 语句，因为它具有相同的目的。有关更多信息，请参阅 [处理 JSON 格式的 Amazon RDS 数据 API 查询结果](data-api-json.md)。