Skip to content

Updated README.md to match current design iteration of interface #1616

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jan 24, 2020
Merged

Updated README.md to match current design iteration of interface #1616

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 61 additions & 37 deletions services-custom/dynamodb-enhanced/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,18 +41,26 @@ values used are also completely arbitrary.
class itself, or somewhere else :-
```java
static final TableSchema<Customer> CUSTOMER_TABLE_SCHEMA =
TableSchema.builder()
StaticTableSchema.builder()
.newItemSupplier(Customer::new) // Tells the mapper how to make new objects when reading items
.attributes(
string("account_id", Customer::getAccountId, Customer::setAccountId)
stringAttribute("account_id",
Customer::getAccountId,
Customer::setAccountId)
.as(primaryPartitionKey()), // primary partition key
integerNumber("sub_id", Customer::getSubId, Customer::setSubId)
integerNumberAttribute("sub_id",
Customer::getSubId,
Customer::setSubId)
.as(primarySortKey()), // primary sort key
string("name", Customer::getName, Customer::setName)
stringAttribute("name",
Customer::getName,
Customer::setName)
.as(secondaryPartitionKey("customers_by_name")), // GSI partition key
string("created_date", Customer::getCreatedDate, Customer::setCreatedDate)
.as(secondarySortKey("customers_by_date"), secondarySortKey("customers_by_name")) // Sort key for both the LSI and the GSI
)
stringAttribute("created_date",
Customer::getCreatedDate,
Customer::setCreatedDate)
.as(secondarySortKey("customers_by_date"),
secondarySortKey("customers_by_name"))) // Sort key for both the LSI and the GSI
.build();
```

Expand Down Expand Up @@ -82,36 +90,50 @@ available in the low-level DynamoDB SDK client.
customerTable.execute(CreateTable.create());

// GetItem
Customer customer = customerTable.execute(GetItem.of(Key.of(stringValue("a123"))));
Customer customer = customerTable.execute(GetItem.create(Key.create(stringValue("a123"))));

// UpdateItem
Customer updatedCustomer = customerTable.execute(UpdateItem.of(customer));
Customer updatedCustomer = customerTable.execute(UpdateItem.create(customer));

// PutItem
customerTable.execute(PutItem.of(customer));
customerTable.execute(PutItem.create(customer));

// DeleteItem
Customer deletedCustomer = customerTable.execute(DeleteItem.of(Key.of(stringValue("a123"), numberValue(456))));
Customer deletedCustomer = customerTable.execute(DeleteItem.create(Key.create(stringValue("a123"), numberValue(456))));

// Query
Iterable<Page<Customer>> customers = customerTable.execute(Query.of(equalTo(Key.of(stringValue("a123")))));
Iterable<Page<Customer>> customers = customerTable.execute(Query.create(equalTo(Key.create(stringValue("a123")))));

// Scan
Iterable<Page<Customer>> customers = customerTable.execute(Scan.create());

// BatchGetItem
batchResults = database.execute(BatchGetItem.of(ReadBatch.of(customerTable, GetItem.of(key1), GetItem.of(key2), GetItem.of(key3)));
batchResults = database.execute(
BatchGetItem.create(
ReadBatch.create(customerTable,
GetItem.create(key1),
GetItem.create(key2),
GetItem.create(key3))));

// BatchWriteItem
batchResults = database.execute(BatchWriteItem.of(WriteBatch.of(customerTable, PutItem.of(item), DeleteItem.of(key1), DeleteItem.of(key2))));
batchResults = database.execute(
BatchWriteItem.create(
WriteBatch.create(customerTable,
PutItem.create(item),
DeleteItem.create(key1),
DeleteItem.create(key2))));

// TransactGetItems
transactResults = mappedDatabase.execute(TransactGetItems.of(ReadTransaction.of(customerTable, GetItem.of(key1)),
ReadTransaction.of(orderTable, GetItem.of(key2)));
transactResults = mappedDatabase.execute(
TransactGetItems.create(
ReadTransaction.create(customerTable, GetItem.create(key1)),
ReadTransaction.create(orderTable, GetItem.create(key2))));

// TransactWriteItems
mappedDatabase.execute(TransactWriteItems.of(WriteTransaction.of(customerTable, UpdateItem.of(customer)),
WriteTransaction.of(orderTable, ConditionCheck.of(orderKey, conditionExpression)));
mappedDatabase.execute(
TransactWriteItems.create(
WriteTransaction.create(customerTable, UpdateItem.create(customer)),
WriteTransaction.create(orderTable, ConditionCheck.create(orderKey, conditionExpression))));
```

### Using secondary indices
Expand All @@ -120,7 +142,7 @@ index. Here's an example of how to do this:
```
MappedIndex<Customer> customersByName = customerTable.index("customers_by_name");

Iterable<Page<Customer>> customersWithName = customersByName.query(equalTo(Key.of(stringValue("Smith"))));
Iterable<Page<Customer>> customersWithName = customersByName.query(equalTo(Key.create(stringValue("Smith"))));
```

### Non-blocking asynchronous operations
Expand All @@ -134,7 +156,7 @@ key differences:
an asynchronous DynamoDb client from the SDK as well):
```java
AsyncMappedDatabase database = DynamoDbAsyncMappedDatabase.builder()
.dynamoDbAsyncClient(dynamoDbAsyncClient)
.dynamoDbClient(dynamoDbAsyncClient)
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if you also want to update the name of the arg

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was deliberate to show that we were actually passing in an async client.

.build();
```

Expand All @@ -143,7 +165,7 @@ key differences:
application can then do other work without having to block on the
result:
```java
CompletableFuture<Customer> result = mappedTable.execute(GetItem.of(customerKey));
CompletableFuture<Customer> result = mappedTable.execute(GetItem.create(customerKey));
// Perform other work here
return result.join(); // now block and wait for the result
```
Expand Down Expand Up @@ -184,18 +206,20 @@ that write will fail.
To load the extension:
```java
MappedDatabase database =
MappedDatabase.builder()
.dynamoDbClient(dynbamoDbClient)
.extendWith(VersionedRecordExtension.builder().build())
.build();
DynamoDbMappedDatabase.builder()
.dynamoDbClient(dynbamoDbClient)
.extendWith(VersionedRecordExtension.builder().build())
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a create method on VersionedRecordExtension if it can be done no-args?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There probably should be, but there isn't, so this is accurate. We plan to integrate that plugin into the core of the mapper anyway so it will be moot soon.

.build();
```

To tell the extension which attribute to use to track the record version
number tag a numeric attribute in the TableSchema with the version()
AttributeTag:
```java
integerNumber("version", Customer::getVersion, Customer::setVersion)
.as(version())
integerNumberAttribute("version",
Customer::getVersion,
Customer::setVersion)
.as(version()) // Apply the 'version' tag to the attribute
```

## Advanced scenarios
Expand All @@ -219,18 +243,18 @@ public abstract class GenericRecord {
}

private static final StaticTableSchema<GenericRecord> GENERIC_RECORD_SCHEMA =
TableSchema.builder()
StaticTableSchema.builder()
.attributes(
// The partition key will be inherited by the top level mapper
string("id", GenericRecord::getId, GenericRecord::setId).as(primaryPartitionKey()),
string("created_date", GenericRecord::getCreatedDate, GenericRecord::setCreatedDate))
stringAttribute("id", GenericRecord::getId, GenericRecord::setId).as(primaryPartitionKey()),
stringAttribute("created_date", GenericRecord::getCreatedDate, GenericRecord::setCreatedDate))
.build();

private static final StaticTableSchema<Customer> CUSTOMER_TABLE_SCHEMA =
TableSchema.builder()
StaticTableSchema.builder()
.newItemSupplier(Customer::new)
.attributes(
string("name", Customer::getName, Customer::setName))
stringAttribute("name", Customer::getName, Customer::setName))
.extend(GENERIC_RECORD_SCHEMA) // All the attributes of the GenericRecord schema are added to Customer
.build();
```
Expand All @@ -250,17 +274,17 @@ public class GenericRecord {
}

private static final StaticTableSchema<GenericRecord> GENERIC_RECORD_SCHEMA =
TableSchema.builder()
StaticTableSchema.builder()
.newItemSupplier(GenericRecord::new)
.attributes(
string("id", GenericRecord::getId, GenericRecord::setId).as(primaryPartitionKey()),
string("created_date", GenericRecord::getCreatedDate, GenericRecord::setCreatedDate))
stringAttribute("id", GenericRecord::getId, GenericRecord::setId).as(primaryPartitionKey()),
stringAttribute("created_date", GenericRecord::getCreatedDate, GenericRecord::setCreatedDate))
.build();

private static final StaticTableSchema<Customer> CUSTOMER_TABLE_SCHEMA =
TableSchema.builder()
StaticTableSchema.builder()
.newItemSupplier(Customer::new)
.attributes(string("name", Customer::getName, Customer::setName))
.attributes(stringAttribute("name", Customer::getName, Customer::setName))
// Because we are flattening a component object, we supply a getter and setter so the
// mapper knows how to access it
.flatten(CUSTOMER_TABLE_SCHEMA, Customer::getRecordMetadata, Customer::setRecordMetadata)
Expand Down