Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# DynamoDB memetakan perbedaan API antara versi 1 dan versi 2 AWS SDK untuk Java
APIs Pemetaan DynamoDB berubah secara signifikan antara versi 1 dan versi 2. AWS SDK untuk Java Di versi 1, Anda menggunakan `DynamoDBMapper` untuk bekerja dengan Java POJOs. Di versi 2, Anda menggunakan nama metode `DynamoDbEnhancedClient` yang diperbarui, opsi definisi skema yang disempurnakan, dan keamanan tipe yang ditingkatkan.
Perbedaan utama meliputi:
+ Nama metode baru (seperti `getItem` bukan`load`)
+ Pembuatan skema tabel eksplisit
+ Dukungan bawaan untuk operasi sinkron dan asinkron
+ Perubahan cara string dan konfigurasi kosong ditangani
Bagian ini mencakup perubahan API pemetaan, perbedaan anotasi, pembaruan konfigurasi, dan panduan migrasi untuk membantu Anda bertransisi dari v1 `DynamoDBMapper` ke v2. `DynamoDbEnhancedClient`
**Contents**
+ [Perubahan tingkat tinggi dalam pemetaan pustaka dari versi 1 ke versi 2 SDK for Java](dynamodb-mapping-high-level.md)
+ [Perbedaan ketergantungan impor](dynamodb-mapping-high-level.md#dynamodb-mapping-deps)
+ [Perubahan dalam APIs pemetaan DynamoDB antara versi 1 dan versi 2 dari SDK for Java](dynamodb-mapping-api-changes.md)
+ [Buat klien](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-client)
+ [Menetapkan pemetaan ke tabel/indeks DynamoDB](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-mapping)
+ [Operasi tabel](dynamodb-mapping-api-changes.md#dynamodb-mapping-api-changes-tobleops)
+ [Kelas peta dan properti](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas)
+ [Anotasi kacang](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos)
+ [V2 anotasi tambahan](dynamodb-mapping-api-changes.md#dynamodb-mapping-schemas-annos-v2-addnl)
+ [Konfigurasi](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration)
+ [Konfigurasi per operasi](dynamodb-mapping-api-changes.md#dynamodb-mapping-configuration-per-op)
+ [Kondisional](dynamodb-mapping-api-changes.md#dynamodb-mapping-conditionals)
+ [Jenis konversi](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv)
+ [Konverter default](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-defaults)
+ [Menetapkan konverter kustom untuk atribut](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-anno)
+ [Tambahkan pabrik atau penyedia konverter tipe](dynamodb-mapping-api-changes.md#dynamodb-mapping-type-conv-factory)
+ [String menangani perbedaan antara versi 1 dan versi 2 dari SDK for Java](dynamodb-migration-string-handling.md)
+ [Perbedaan penguncian optimis antara versi 1 dan versi 2 dari SDK for Java](dynamodb-migrate-optimstic-locking.md)
+ [Perbedaan setter yang lancar antara versi 1 dan versi 2 dari SDK for Java](dynamodb-migrate-fluent-setters.md)
# Perubahan tingkat tinggi dalam pemetaan pustaka dari versi 1 ke versi 2 SDK for Java
Nama-nama klien pemetaan di setiap pustaka berbeda di V1 dan V2:
+ V1 - Dinamo DBMapper
+ V2 - Klien yang Ditingkatkan DynamoDB
Anda berinteraksi dengan dua pustaka dengan cara yang hampir sama: Anda membuat instance mapper/client dan kemudian memasok POJO Java untuk membaca dan menulis item ini ke APIs tabel DynamoDB. Kedua pustaka juga menawarkan anotasi untuk kelas POJO untuk mengarahkan bagaimana klien menangani POJO.
Perbedaan penting saat Anda pindah ke V2 meliputi:
+ V2 dan V1 menggunakan nama metode yang berbeda untuk operasi DynamoDB tingkat rendah. Contoh:
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/dynamodb-mapping-high-level.html)
+ V2 menawarkan beberapa cara untuk menentukan skema tabel dan memetakan POJOs ke tabel. Anda dapat memilih dari penggunaan anotasi atau skema yang dihasilkan dari kode menggunakan pembangun. V2 juga menawarkan versi skema yang dapat berubah dan tidak dapat diubah.
+ Dengan V2, Anda secara khusus membuat skema tabel sebagai salah satu langkah pertama, sedangkan di V1, skema tabel disimpulkan dari kelas beranotasi sesuai kebutuhan.
+ V2 menyertakan [klien Document API](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/document/EnhancedDocument.html) dalam API klien yang disempurnakan, sedangkan V1 menggunakan [API terpisah](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/document/DynamoDB.html).
+ Semua APIs tersedia dalam versi sinkron dan asinkron di V2.
Lihat bagian [pemetaan DynamoDB](dynamodb-enhanced-client.md) dalam panduan ini untuk informasi lebih rinci tentang klien yang disempurnakan V2.
## Perbedaan ketergantungan impor
| V1 | V2 |
| --- | --- |
|
com.amazonaws
aws-java-sdk-bom
1.X.X
pom
import
com.amazonaws
aws-java-sdk-dynamodb
|
software.amazon.awssdk
bom
2.X.X*
pom
import
software.amazon.awssdk
dynamodb-enhanced
|
\$1 [Versi terbaru](https://central.sonatype.com/artifact/software.amazon.awssdk/bom).
Di V1, dependensi tunggal mencakup API DynamoDB tingkat rendah dan mapping/document API, sedangkan di V2, Anda menggunakan `dynamodb-enhanced` dependensi artefak untuk mengakses API. mapping/document `dynamodb-enhanced`Modul ini berisi ketergantungan transitif pada modul tingkat rendah`dynamodb`.
# Perubahan dalam APIs pemetaan DynamoDB antara versi 1 dan versi 2 dari SDK for Java
## Buat klien
****
| Kasus penggunaan | V1 | V2 |
| --- | --- | --- |
| Instantiasi normal | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard()
.withCredentials(credentialsProvider)
.withRegion(Regions.US_EAST_1)
.build();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbClient standardClient = DynamoDbClient.builder()
.credentialsProvider(ProfileCredentialsProvider.create())
.region(Region.US_EAST_1)
.build();
DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.build();
|
| Instantiasi minimal | AmazonDynamoDB standardClient = AmazonDynamoDBClientBuilder.standard();
DynamoDBMapper mapper = new DynamoDBMapper(standardClient);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.create();
|
| Dengan trafo atribut\$1 | DynamoDBMapper mapper = new DynamoDBMapper(standardClient,
attributeTransformerInstance);
| DynamoDbEnhancedClient enhancedClient = DynamoDbEnhancedClient.builder()
.dynamoDbClient(standardClient)
.extensions(extensionAInstance, extensionBInstance)
.build();
|
\$1 Ekstensi di V2 kira-kira sesuai dengan atribut transformer di V1. [Gunakan ekstensi untuk menyesuaikan operasi DynamoDB Enhanced Client](ddb-en-client-extensions.md)Bagian ini berisi informasi lebih lanjut tentang ekstensi di V2.
## Menetapkan pemetaan ke tabel/indeks DynamoDB
Di V1, Anda menentukan nama tabel DynamoDB melalui anotasi kacang. Dalam V2, metode pabrik,`table()`, menghasilkan instance `DynamoDbTable` yang mewakili tabel DynamoDB jarak jauh. Parameter pertama dari `table()` metode ini adalah nama tabel DynamoDB.
****
| Kasus penggunaan | V1 | V2 |
| --- | --- | --- |
| Memetakan kelas Java POJO ke tabel DynamoDB | @DynamoDBTable(tableName ="Customer")
public class Customer {
...
}
| DynamoDbTable customerTable = enhancedClient.table("Customer",
TableSchema.fromBean(Customer.class));
|
| Peta ke indeks sekunder DynamoDB | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) Bagian dalam DynamoDB Developer Guide yang [membahas metode `query` V1 menunjukkan contoh](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.Methods.html#DynamoDBMapper.Methods.query) lengkap. | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) [Gunakan indeks sekunder](ddb-en-client-use-secindex.md)Bagian dalam panduan ini memberikan informasi lebih lanjut. |
## Operasi tabel
Bagian ini menjelaskan operasi APIs yang berbeda antara V1 dan V2 untuk sebagian besar kasus penggunaan standar.
Di V2, semua operasi yang melibatkan satu tabel dipanggil pada `DynamoDbTable` instance, bukan pada klien yang disempurnakan. Klien yang disempurnakan berisi metode yang dapat menargetkan beberapa tabel.
Dalam tabel bernama *operasi Tabel* di bawah ini, contoh POJO disebut sebagai `item` atau sebagai tipe tertentu seperti`customer1`. Untuk contoh V2 instance bernama, `table` adalah hasil dari pemanggilan sebelumnya `enhancedClient.table()` yang mengembalikan referensi ke `DynamoDbTable` instance.
Perhatikan bahwa sebagian besar operasi V2 dapat dipanggil dengan pola konsumen yang lancar bahkan ketika tidak ditampilkan. Misalnya,
```
Customer customer = table.getItem(r → r.key(key));
or
Customer customer = table.getItem(r → r.key(k -> k.partitionValue("id").sortValue("email")))
```
Untuk operasi V1, *operasi Tabel* (di bawah) berisi beberapa formulir yang umum digunakan dan tidak semua formulir yang kelebihan beban. Misalnya, `load()` metode ini memiliki kelebihan beban berikut:
```
mapper.load(Customer.class, hashKey)
mapper.load(Customer.class, hashKey, rangeKey)
mapper.load(Customer.class, hashKey, config)
mapper.load(Customer.class, hashKey, rangeKey, config)
mapper.load(item)
mapper.load(item, config)
```
*Operasi tabel* (di bawah) menunjukkan bentuk yang umum digunakan:
```
mapper.load(item)
mapper.load(item, config)
```
**Operasi tabel**
| Kasus penggunaan | V1 | V2 |
| --- | --- | --- |
| Tulis POJO Java ke tabel DynamoDB **Operasi DynamoDB**:, `PutItem` `UpdateItem` | mapper.save(item)
mapper.save(item, config)
mapper.save(item, saveExpression, config)
Dalam V1, `DynamoDBMapperConfig.SaveBehavior` dan anotasi menentukan metode DynamoDB tingkat rendah mana yang akan dipanggil. Secara umum, `UpdateItem` disebut kecuali saat menggunakan `SaveBehavior.CLOBBER` dan`SaveBehavior.PUT`. Kunci yang dihasilkan secara otomatis adalah kasus penggunaan khusus, dan kadang-kadang keduanya `PutItem` dan `UpdateItem` digunakan. | table.putItem(putItemRequest)
table.putItem(item)
table.putItemWithResponse(item) //Returns metadata.
updateItem(updateItemRequest)
table.updateItem(item)
table.updateItemWithResponse(item) //Returns metadata.
|
| Membaca item dari tabel DynamoDB ke POJO Java **Operasi DynamoDB:** `GetItem` | mapper.load(item)
mapper.load(item, config)
| table.getItem(getItemRequest)
table.getItem(item)
table.getItem(key)
table.getItemWithResponse(key) //Returns POJO with metadata.
|
| Menghapus item dari tabel DynamoDB **Operasi DynamoDB:** `DeleteItem` | mapper.delete(item, deleteExpression, config)
| table.deleteItem(deleteItemRequest)
table.deleteItem(item)
table.deleteItem(key)
|
| Kueri tabel DynamoDB atau indeks sekunder dan kembalikan daftar paginasi **Operasi DynamoDB:** `Query` | mapper.query(Customer.class, queryExpression)
mapper.query(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
Gunakan yang dikembalikan `PageIterable.stream()` (pemuatan lambat) untuk respons sinkronisasi dan `PagePublisher.subscribe()` untuk respons asinkron |
| Kueri tabel DynamoDB atau indeks sekunder dan kembalikan daftar **Operasi DynamoDB:** `Query` | mapper.queryPage(Customer.class, queryExpression)
mapper.queryPage(Customer.class, queryExpression,
mapperConfig)
| table.query(queryRequest)
table.query(queryConditional)
Gunakan yang dikembalikan `PageIterable.items()` (pemuatan lambat) untuk respons sinkronisasi dan `PagePublisher.items.subscribe()` untuk respons asinkron |
| Memindai tabel DynamoDB atau indeks sekunder dan mengembalikan daftar paginasi **Operasi DynamoDB:** `Scan` | mapper.scan(Customer.class, scanExpression)
mapper.scan(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
Gunakan yang dikembalikan `PageIterable.stream()` (pemuatan lambat) untuk respons sinkronisasi dan `PagePublisher.subscribe()` untuk respons asinkron |
| Pindai tabel DynamoDB atau indeks sekunder dan kembalikan daftar **Operasi DynamoDB:** `Scan` | mapper.scanPage(Customer.class, scanExpression)
mapper.scanPage(Customer.class, scanExpression,
mapperConfig)
| table.scan()
table.scan(scanRequest)
Gunakan yang dikembalikan `PageIterable.items()` (pemuatan lambat) untuk respons sinkronisasi dan `PagePublisher.items.subscribe()` untuk respons asinkron |
| Baca beberapa item dari beberapa tabel dalam satu batch **Operasi DynamoDB:** `BatchGetItem` | mapper.batchLoad(Arrays.asList(customer1,
customer2,
book1))
mapper.batchLoad(itemsToGet)
// itemsToGet: Map, List>
| enhancedClient.batchGetItem(batchGetItemRequest)
enhancedClient.batchGetItem(r -> r.readBatches(
ReadBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build(),
ReadBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addGetItem(i -> i.key(k -> k.partitionValue(0)))
.build()))
// Iterate over pages with lazy loading or over all items
from the same table.
|
| Tulis beberapa item ke beberapa tabel dalam satu batch **Operasi DynamoDB:** `BatchWriteItem` | mapper.batchSave(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(batchWriteItemRequest)
enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addPutItem(item2)
.build()))
|
| Hapus beberapa item dari beberapa tabel dalam satu batch **Operasi DynamoDB:** `BatchWriteItem` | mapper.batchDelete(Arrays.asList(customer1,
customer2,
book1))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addDeleteItem(item1key)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| Tulis/hapus beberapa item dalam satu batch **Operasi DynamoDB:** `BatchWriteItem` | mapper.batchWrite(Arrays.asList(customer1, book1),
Arrays.asList(customer2))
| enhancedClient.batchWriteItem(r -> r.writeBatches(
WriteBatch.builder(Record1.class)
.mappedTableResource(mappedTable1)
.addPutItem(item1)
.build(),
WriteBatch.builder(Record2.class)
.mappedTableResource(mappedTable2)
.addDeleteItem(item2key)
.build()))
|
| Lakukan penulisan transaksional **Operasi DynamoDB:** `TransactWriteItems` | mapper.transactionWrite(transactionWriteRequest)
| enhancedClient.transactWriteItems(transasctWriteItemsRequest)
|
| Lakukan pembacaan transaksional **Operasi DynamoDB:** `TransactGetItems` | mapper.transactionLoad(transactionLoadRequest)
| enhancedClient.transactGetItems(transactGetItemsRequest)
|
| Dapatkan hitungan item yang cocok dari kueri **Operasi DynamoDB**: dengan `Query` `Select.COUNT` | mapper.count(Customer.class, queryExpression)
| // Get the count from query results.
PageIterable pageIterable =
customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.query(QueryEnhancedRequest.builder()
.queryConditional(queryConditional)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| Dapatkan hitungan item yang cocok dari pemindaian **Operasi DynamoDB**: dengan `Scan` `Select.COUNT` | mapper.count(Customer.class, scanExpression)
| // Get the count from scan results.
PageIterable pageIterable =
customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build());
Iterator> iterator = pageIterable.iterator();
Page page = iterator.next();
int count = page.count();
// For a more concise approach, you can chain the method calls:
int count = customerTable.scan(ScanEnhancedRequest.builder()
.filterExpression(filterExpression)
.select(Select.COUNT)
.build())
.iterator().next().count();
|
| Buat tabel di DynamoDB sesuai dengan kelas POJO **Operasi DynamoDB:** `CreateTable` | mapper.generateCreateTableRequest(Customer.class)
Pernyataan sebelumnya menghasilkan permintaan tabel buat tingkat rendah; pengguna harus memanggil klien `createTable` DynamoDB. | table.createTable(createTableRequest)
table.createTable(r -> r.provisionedThroughput(defaultThroughput())
.globalSecondaryIndices(
EnhancedGlobalSecondaryIndex.builder()
.indexName("gsi_1")
.projection(p -> p.projectionType(ProjectionType.ALL))
.provisionedThroughput(defaultThroughput())
.build()));
|
| Lakukan pemindaian paralel di DynamoDB **Operasi `Scan` DynamoDB**: dengan dan parameter `Segment` `TotalSegments` | mapper.parallelScan(Customer.class,
scanExpression,
numTotalSegments)
| Pengguna diminta untuk menangani thread pekerja dan memanggil `scan` untuk setiap segmen: table.scan(r -> r.segment(0).totalSegments(5))
|
| Integrasikan Amazon S3 dengan DynamoDB untuk menyimpan tautan S3 cerdas | mapper.createS3Link(bucket, key)
mapper.getS3ClientCache()
| Tidak didukung karena memasangkan Amazon S3 dan DynamoDB. |
## Kelas peta dan properti
Di V1 dan V2, Anda memetakan kelas ke tabel menggunakan anotasi gaya kacang. V2 juga menawarkan [cara lain untuk mendefinisikan skema](ddb-en-client-adv-features.md#ddb-en-client-adv-features-schm-overview) untuk kasus penggunaan tertentu, seperti bekerja dengan kelas yang tidak dapat diubah.
### Anotasi kacang
Tabel berikut menunjukkan anotasi kacang setara untuk kasus penggunaan tertentu yang digunakan dalam V1 dan V2. Skenario `Customer` kelas digunakan untuk mengilustrasikan parameter.
Anotasi — serta kelas dan pencacahan — di V2 ikuti konvensi kasus unta dan gunakan '', bukan 'DynamoDB'. DynamoDb
| Kasus penggunaan | V1 | V2 |
| --- | --- | --- |
| Petakan kelas ke tabel | @DynamoDBTable (tableName ="CustomerTable")
| @DynamoDbBean
@DynamoDbBean(converterProviders = {...})
Nama tabel didefinisikan saat memanggil DynamoDbEnhancedClient\$1table() metode. |
| Menunjuk anggota kelas sebagai atribut tabel | @DynamoDBAttribute(attributeName = "customerName")
| @DynamoDbAttribute("customerName") |
| Menunjuk anggota kelas adalah kunci hash/partition | @DynamoDBHashKey
| @DynamoDbPartitionKey
|
| Menunjuk anggota kelas adalah kunci range/sort | @DynamoDBRangeKey
| @DynamoDbSortKey
|
| Menunjuk anggota kelas adalah kunci hash/partisi indeks sekunder | @DynamoDBIndexHashKey
| @DynamoDbSecondaryPartitionKey
|
| Menunjuk anggota kelas adalah kunci rentang/sortir indeks sekunder | @DynamoDBIndexRangeKey
| @DynamoDbSecondarySortKey
|
| Abaikan anggota kelas ini saat memetakan ke tabel | @DynamoDBIgnore
| @DynamoDbIgnore
|
| Tentukan anggota kelas sebagai atribut kunci UUID yang dibuat secara otomatis | @DynamoDBAutoGeneratedKey
| @DynamoDbAutoGeneratedUuid
Ekstensi yang menyediakan ini tidak dimuat secara default; Anda harus menambahkan ekstensi ke pembuat klien. |
| Tentukan anggota kelas sebagai atribut stempel waktu yang dibuat secara otomatis | @DynamoDBAutoGeneratedTimestamp
| @DynamoDbAutoGeneratedTimestampAttribute
Ekstensi yang menyediakan ini tidak dimuat secara default; Anda harus menambahkan ekstensi ke pembuat klien. |
| Menunjuk anggota kelas sebagai atribut versi auto-incremented | @DynamoDBVersionAttribute
| @DynamoDbVersionAttribute
Ekstensi yang menyediakan ini dimuat secara otomatis. |
| Menunjuk anggota kelas sebagai membutuhkan konversi kustom | @DynamoDBTypeConverted
| @DynamoDbConvertedBy
|
| Menunjuk anggota kelas untuk disimpan sebagai jenis atribut yang berbeda | @DynamoDBTyped()
| Gunakan `AttributeConverter` implementasi. V2 menyediakan banyak konverter bawaan untuk tipe Java umum. Anda juga dapat menerapkan kebiasaan Anda sendiri `AttributeConverter` atau`AttributeConverterProvider`. Lihat [Konversi atribut kontrol](ddb-en-client-adv-features-conversion.md) di panduan ini. |
| Tentukan kelas yang dapat diserialisasikan ke dokumen DynamoDB (dokumen gaya JSON) atau sub-dokumen | @DynamoDBDocument
| Gunakan API Dokumen yang Ditingkatkan. Lihat sumber daya berikut:[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
### V2 anotasi tambahan
| Kasus penggunaan | V1 | V2 |
| --- | --- | --- |
| Menunjuk anggota kelas untuk tidak disimpan sebagai atribut NULL jika nilai Java adalah null | N/A | @DynamoDbIgnoreNulls
|
| Menunjuk anggota kelas untuk menjadi objek kosong jika semua atribut adalah null | N/A | @DynamoDbPreserveEmptyObject
|
| Tentukan tindakan pembaruan khusus untuk anggota kelas | N/A | @DynamoDbUpdateBehavior
|
| Tentukan kelas yang tidak dapat diubah | N/A | @DynamoDbImmutable
|
| Menunjuk anggota kelas sebagai atribut counter auto-incremented | N/A | @DynamoDbAtomicCounter
Ekstensi yang menyediakan fungsi ini dimuat secara otomatis. |
## Konfigurasi
Di V1, Anda biasanya mengontrol perilaku tertentu dengan menggunakan instance dari. `DynamoDBMapperConfig` Anda dapat menyediakan objek konfigurasi baik ketika Anda membuat mapper atau ketika Anda membuat permintaan. Dalam V2, konfigurasi khusus untuk objek permintaan untuk operasi.
| Kasus penggunaan | V1 | Default di V1 | V2 |
| --- | --- | --- | --- |
| | DynamoDBMapperConfig.builder()
| | |
| Strategi load/write coba lagi Batch | .withBatchLoadRetryStrategy(loadRetryStrategy)
.withBatchWriteRetryStrategy(writeRetryStrategy)
| coba lagi item yang gagal | Konfigurasikan strategi coba lagi pada yang mendasarinyaDynamoDBClient. Lihat [Konfigurasikan perilaku coba lagi di AWS SDK for Java 2.x](retry-strategy.md) di panduan ini. |
| Bacaan yang konsisten | .withConsistentReads(CONSISTENT)
| EVENTUAL | Secara default, pembacaan konsisten salah untuk operasi baca. Ganti dengan .consistentRead(true) objek permintaan. |
| Skema konversi dengan set marshallers/unmarshallers | .withConversionSchema(conversionSchema)
Implementasi statis memberikan kompatibilitas mundur dengan versi yang lebih lama. | V2\$1COMPATIBLE | Tidak berlaku. Ini adalah fitur lama yang mengacu pada bagaimana versi awal DynamoDB (V1) menyimpan tipe data, dan perilaku ini tidak akan dipertahankan di klien yang disempurnakan. Contoh perilaku di DynamoDB V1 adalah menyimpan boolean sebagai Number, bukan sebagai Boolean. |
| Nama tabel | .withObjectTableNameResolver()
.withTableNameOverride()
.withTableNameResolver()
Implementasi statis memberikan kompatibilitas mundur dengan versi yang lebih lama | gunakan anotasi atau tebakan dari kelas | Nama tabel didefinisikan saat memanggil `DynamoDbEnhancedClient#table()` metode. |
| Strategi beban pagination | .withPaginationLoadingStrategy(strategy)
Pilihannya adalah: LAZY\$1`LOADING`,, `EAGER_LOADING` atau `ITERATION_ONLY` | LAZY\$1LOADING | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/id_id/sdk-for-java/latest/developer-guide/dynamodb-mapping-api-changes.html) |
| Minta pengumpulan metrik | .withRequestMetricCollector(collector)
| null | Gunakan metricPublisher() ClientOverrideConfiguration saat membangun klien DynamoDB standar. |
| Simpan perilaku | .withSaveBehavior(SaveBehavior.CLOBBER)
Pilihannya adalah `UPDATE``CLOBBER`,,`PUT`,`APPEND_SET`, atau`UPDATE_SKIP_NULL_ATTRIBUTES`. | UPDATE | Di V2, Anda menelepon `putItem()` atau `updateItem()` secara eksplisit. `CLOBBER or PUT`: Tindakan yang sesuai di v 2 memanggil`putItem()`. Tidak ada `CLOBBER` konfigurasi khusus. `UPDATE`: Sesuai dengan `updateItem()` `UPDATE_SKIP_NULL_ATTRIBUTES`: Sesuai dengan`updateItem()`. Kontrol perilaku pembaruan dengan setelan permintaan `ignoreNulls` dan anotasi/tag`DynamoDbUpdateBehavior`. `APPEND_SET`: Tidak didukung |
| Jenis konverter pabrik | .withTypeConverterFactory(typeConverterFactory)
| konverter tipe standar | Atur kacang dengan menggunakan @DynamoDbBean(converterProviders = {ConverterProvider.class,
DefaultAttributeConverterProvider.class}) |
### Konfigurasi per operasi
Di V1, beberapa operasi, seperti`query()`, sangat dapat dikonfigurasi melalui objek “ekspresi” yang dikirimkan ke operasi. Contoh:
```
DynamoDBQueryExpression emailBwQueryExpr = new DynamoDBQueryExpression()
.withRangeKeyCondition("Email",
new Condition()
.withComparisonOperator(ComparisonOperator.BEGINS_WITH)
.withAttributeValueList(
new AttributeValue().withS("my")));
mapper.query(Customer.class, emailBwQueryExpr);
```
Di V2, alih-alih menggunakan objek konfigurasi, Anda menetapkan parameter pada objek permintaan dengan menggunakan pembuat. Contoh:
```
QueryEnhancedRequest emailBw = QueryEnhancedRequest.builder()
.queryConditional(QueryConditional
.sortBeginsWith(kb -> kb
.sortValue("my"))).build();
customerTable.query(emailBw);
```
## Kondisional
Dalam V2, ekspresi kondisional dan penyaringan diekspresikan menggunakan `Expression` objek, yang merangkum kondisi dan pemetaan nama dan filter.
| Kasus penggunaan | Operasi | V1 | V2 |
| --- | --- | --- | --- |
| Kondisi atribut yang diharapkan | save (), delete (), query (), scan () | new DynamoDBSaveExpression()
.withExpected(Collections.singletonMap(
"otherAttribute", new ExpectedAttributeValue(false)))
.withConditionalOperator(ConditionalOperator.AND);
| Usang; gunakan sebagai gantinya. ConditionExpression |
| Ekspresi kondisi | hapus () | deleteExpression.setConditionExpression("zipcode = :zipcode")
deleteExpression.setExpressionAttributeValues(...)
| Expression conditionExpression =
Expression.builder()
.expression("#key = :value OR #key1 = :value1")
.putExpressionName("#key", "attribute")
.putExpressionName("#key1", "attribute3")
.putExpressionValue(":value", AttributeValues.stringValue("wrong"))
.putExpressionValue(":value1", AttributeValues.stringValue("three"))
.build();
DeleteItemEnhancedRequest request = DeleteItemEnhancedRequest.builder()
.conditionExpression(conditionExpression).build();
|
| Ekspresi filter | query (), scan () | scanExpression
.withFilterExpression("#statename = :state")
.withExpressionAttributeValues(attributeValueMapBuilder.build())
.withExpressionAttributeNames(attributeNameMapBuilder.build())
| Map values = singletonMap(":key", stringValue("value"));
Expression filterExpression =
Expression.builder()
.expression("name = :key")
.expressionValues(values)
.build();
QueryEnhancedRequest request = QueryEnhancedRequest.builder()
.filterExpression(filterExpression).build();
|
| Ekspresi kondisi untuk kueri | kueri () | queryExpression.withKeyConditionExpression()
| QueryConditional keyEqual = QueryConditional.keyEqualTo(b -> b
.partitionValue("movie01"));
QueryEnhancedRequest tableQuery = QueryEnhancedRequest.builder()
.queryConditional(keyEqual)
.build();
|
## Jenis konversi
### Konverter default
Di V2, SDK menyediakan satu set konverter default untuk semua tipe umum. Anda dapat mengubah konverter tipe baik di tingkat penyedia keseluruhan maupun untuk satu atribut. Anda dapat menemukan daftar konverter yang tersedia di referensi [AttributeConverter](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/enhanced/dynamodb/AttributeConverter.html)API.
### Menetapkan konverter kustom untuk atribut
Di V1, Anda dapat membuat anotasi metode pengambil dengan `@DynamoDBTypeConverted` untuk menentukan kelas yang mengkonversi antara tipe atribut Java dan tipe atribut DynamoDB. Misalnya, `CurrencyFormatConverter` yang mengkonversi antara `Currency` tipe Java dan DynamoDB String dapat diterapkan seperti yang ditunjukkan pada cuplikan berikut.
```
@DynamoDBTypeConverted(converter = CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
Setara V2 dari cuplikan sebelumnya ditunjukkan di bawah ini.
```
@DynamoDbConvertedBy(CurrencyFormatConverter.class)
public Currency getCurrency() { return currency; }
```
**catatan**
Di V1, Anda dapat menerapkan anotasi ke atribut itu sendiri, tipe atau anotasi yang ditentukan pengguna, V2 mendukung penerapan anotasi hanya ke pengambil.
### Tambahkan pabrik atau penyedia konverter tipe
Di V1, Anda dapat menyediakan set konverter tipe Anda sendiri, atau mengganti tipe yang Anda pedulikan dengan menambahkan pabrik konverter tipe ke konfigurasi. Pabrik konverter tipe meluas`DynamoDBTypeConverterFactory`, dan penggantian dilakukan dengan mendapatkan referensi ke set default dan memperluasnya. Cuplikan berikut menunjukkan cara melakukan ini.
```
DynamoDBTypeConverterFactory typeConverterFactory =
DynamoDBTypeConverterFactory.standard().override()
.with(String.class, CustomBoolean.class, new DynamoDBTypeConverter() {
@Override
public String convert(CustomBoolean bool) {
return String.valueOf(bool.getValue());
}
@Override
public CustomBoolean unconvert(String string) {
return new CustomBoolean(Boolean.valueOf(string));
}}).build();
DynamoDBMapperConfig config =
DynamoDBMapperConfig.builder()
.withTypeConverterFactory(typeConverterFactory)
.build();
DynamoDBMapper mapperWithTypeConverterFactory = new DynamoDBMapper(dynamo, config);
```
V2 menyediakan fungsionalitas serupa melalui `@DynamoDbBean` anotasi. Anda dapat memberikan satu `AttributeConverterProvider` atau satu rantai pesanan `AttributeConverterProvider` s. Perhatikan bahwa jika Anda menyediakan rantai penyedia konverter atribut Anda sendiri, Anda akan mengganti penyedia konverter default dan harus memasukkannya ke dalam rantai untuk menggunakan konverter atributnya.
```
@DynamoDbBean(converterProviders = {
ConverterProvider1.class,
ConverterProvider2.class,
DefaultAttributeConverterProvider.class})
public class Customer {
...
}
```
Bagian tentang [konversi atribut](ddb-en-client-adv-features-conversion.md#ddb-en-client-adv-features-conversion-example) dalam panduan ini berisi contoh lengkap untuk V2.
# String menangani perbedaan antara versi 1 dan versi 2 dari SDK for Java
V1 dan V2 menangani string kosong secara berbeda saat mengirim data ke DynamoDB:
+ **V1**: Mengkonversi string kosong ke nilai null sebelum mengirim ke DynamoDB (menghasilkan tidak ada atribut)
+ **V2**: Mengirim string kosong sebagai nilai string kosong aktual ke DynamoDB
**penting**
Setelah bermigrasi ke V2, jika Anda tidak ingin string kosong disimpan di DynamoDB, Anda harus menerapkan konverter khusus. Tanpa konverter khusus, V2 menyimpan string kosong sebagai atribut string kosong yang sebenarnya di item DynamoDB Anda, yang berbeda dari perilaku V1 menghilangkan atribut ini sepenuhnya.
**Example konverter khusus untuk V2 yang mengubah atribut string kosong menjadi null**
```
/**
* Custom converter that maintains V1 behavior by converting empty strings to null values
* when writing to DynamoDB, ensuring compatibility with existing data. No attribute will be saved to DynamoDB.
*/
public class NullifyEmptyStringConverter implements AttributeConverter {
@Override
public AttributeValue transformFrom(String value) {
if (value == null || value.isEmpty()) {
return AttributeValue.builder().nul(true).build();
}
return AttributeValue.builder().s(value).build();
}
@Override
public String transformTo(AttributeValue attributeValue) {
if (attributeValue.nul()) {
return null;
}
return attributeValue.s();
}
@Override
public EnhancedType type() {
return EnhancedType.of(String.class);
}
@Override
public AttributeValueType attributeValueType() {
return AttributeValueType.S;
}
}
// V2 usage:
@DynamoDbBean
public class Customer {
private String name;
@DynamoDbConvertedBy(NullifyEmptyStringConverter.class)
public String getName() {
return name;
}
}
```
# Perbedaan penguncian optimis antara versi 1 dan versi 2 dari SDK for Java
Baik V1 dan V2 menerapkan penguncian optimis dengan anotasi atribut yang menandai satu properti di kelas kacang Anda untuk menyimpan nomor versi.
**Perbedaan perilaku penguncian yang optimis**
| | V1 | V2 |
| --- | --- | --- |
| Anotasi kelas kacang | @DynamoDBVersionAttribute | @DynamoDbVersionAttribute(perhatikan bahwa V2 menggunakan huruf kecil “b”) |
| Simpan awal | Atribut nomor versi disetel ke 1. | Nilai awal untuk atribut versi ditetapkan dengan`@DynamoDbVersionAttribute(startAt = X)`. Nilai default-nya adalah 0. |
| Perbarui | Atribut nomor versi bertambah 1 jika pemeriksaan bersyarat memverifikasi bahwa nomor versi objek yang diperbarui cocok dengan nomor dalam database. | Atribut nomor versi bertambah jika pemeriksaan bersyarat memverifikasi bahwa nomor versi objek yang diperbarui cocok dengan nomor dalam database. Atribut nomor versi ditambah dengan `incrementBy` opsi yang ditetapkan dengan`@DynamoDbVersionAttribute(incrementBy = X)`. Nilai default adalah 1. |
| Delete | DynamoDBMappermenambahkan pemeriksaan bersyarat bahwa nomor versi objek yang dihapus cocok dengan nomor versi dalam database. | V2 tidak tidak secara otomatis menambahkan kondisi untuk operasi penghapusan. Anda harus menambahkan ekspresi kondisi secara manual jika Anda ingin mengontrol perilaku hapus. Dalam contoh berikut `recordVersion` adalah atribut versi kacang. // 1. Read the item and get its current version.
Customer item = customerTable.getItem(Key.builder().partitionValue("someId").build());
AttributeValue currentVersion = item.getRecordVersion();
// 2. Create conditional delete with the `currentVersion` value.
DeleteItemEnhancedRequest deleteItemRequest =
DeleteItemEnhancedRequest.builder()
.key(KEY)
.conditionExpression(Expression.builder()
.expression("recordVersion = :current_version_value")
.putExpressionValue(":current_version_value", currentVersion)
.build()).build();
customerTable.deleteItem(deleteItemRequest);
|
| Tulis Transaksional dengan Pemeriksaan Kondisi | Anda tidak dapat menggunakan kelas kacang yang dianotasi dengan @DynamoDBVersionAttribute metode. addConditionCheck | Anda dapat menggunakan kelas kacang dengan @DynamoDbVersionAttribute anotasi dalam metode addConditionCheck pembangun untuk transactWriteItems permintaan. |
| Nonaktifkan | Nonaktifkan penguncian optimis dengan mengubah nilai DynamoDBMapperConfig.SaveBehavior enumerasi dari ke. UPDATE CLOBBER | Jangan gunakan `@DynamoDbVersionAttribute` anotasi. |
# Perbedaan setter yang lancar antara versi 1 dan versi 2 dari SDK for Java
Anda dapat menggunakan POJOs dengan penyetel yang lancar di API pemetaan DynamoDB untuk V1 dan dengan V2 sejak versi 2.30.29.
Misalnya, POJO berikut mengembalikan `Customer` instance dari `setName` metode:
```
// V1
@DynamoDBTable(tableName ="Customer")
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this;
}
}
```
Namun, jika Anda menggunakan versi V2 sebelum 2.30.29, `setName` mengembalikan `Customer` instance dengan `name` nilai. `null`
```
// V2 prior to version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Bug: returns this instance with a `name` value of `null`.
}
}
```
```
// Available in V2 since version 2.30.29.
@DynamoDbBean
public class Customer{
private String name;
// Other attributes and methods not shown.
public Customer setName(String name){
this.name = name;
return this; // Returns this instance for method chaining with the `name` value set.
}
}
```