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

**참고**  
SDK for Java에는 1.x와 2.x의 두 가지 버전이 있습니다. 1.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/). 2025년 12월 31일에 지원이 종료될 예정입니다. 새 개발의 경우 2.x를 사용하는 것이 좋습니다.

AWS SDK for Java에서는 클라이언트 측 클래스를 Amazon DynamoDB 테이블로 매핑할 수 있는 `DynamoDBMapper` 클래스를 제공합니다. `DynamoDBMapper`를 사용하려면 코드에서 DynamoDB 테이블의 항목과 해당하는 객체 인스턴스 간의 관계를 정의합니다. `DynamoDBMapper` 클래스를 사용하면 항목에 대한 다양한 생성, 읽기, 업데이트 및 삭제(CRUD) 작업을 수행하고 테이블에 대한 쿼리 및 스캔을 실행할 수 있습니다.

**Topics**
+ [DynamoDBMapper 클래스](DynamoDBMapper.Methods.md)
+ [Java용 DynamoDBMapper에서 지원되는 데이터 형식](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, ...)
```

아래 Java 코드와 같이 클라이언트 애플리케이션의 클래스를 `ProductCatalog` 테이블로 매핑할 수 있습니다. 이 코드는 `CatalogItem`이라는 POJO(Plain Old Java Object)를 정의합니다. 여기서는 주석을 사용하여 객체 필드를 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 트랜잭션, 자동 생성된 파티션 키 및 정렬 키 값, 객체 버전 관리 등 기본적인 여러 기능을 제공합니다.