Class TableStreamExtensions

Namespace

DynaSharp.Streams

Assembly

DynaSharp.dll

Reads the stream of a table, which DescribeTable names, so the caller needs no ARN.

public static class TableStreamExtensions

Inheritance

object

TableStreamExtensions

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Methods

ReadChangesAsync<T>(Table<T>, DynamoDbStreamsClient, ShardIteratorType, TimeSpan?, Action?, Action<DynamoDbMappingException, ShardChangeRecord>?, CancellationToken)

Reads the changes of the entity of the table from its stream, typed: shop.Of<Order>().ReadChangesAsync(streams, ShardIteratorType.Latest, cancellationToken: ct) gives a Change<T> per change of an order, and skips the other entities of the table.

public static IAsyncEnumerable<Change<T>> ReadChangesAsync<T>(this Table<T> table, DynamoDbStreamsClient streams, ShardIteratorType shardIteratorType, TimeSpan? emptyPageDelay = null, Action? onJoined = null, Action<DynamoDbMappingException, ShardChangeRecord>? onMappingFailure = null, CancellationToken cancellationToken = default) where T : IDynamoDbEntity<T>

Parameters

table Table<T>

The table, whose client describes it.

streams DynamoDbStreamsClient

The client the stream is read with, for the same account and region as the client of the table.

shardIteratorType ShardIteratorType

Where reading starts, see ShardIteratorType.

emptyPageDelay TimeSpan?

The wait after an empty page, see EmptyPageDelay, or null for its default of one second.

onJoined Action

What is called once the reading holds a position in every shard it starts with, see OnJoined, or null.

onMappingFailure Action<DynamoDbMappingException, ShardChangeRecord>

Called when an image has the discriminator of a type of the read but cannot be read as it; the change is then skipped, and counted in dynasharp.client.operation.skipped_items. null, the default, ends the read with the DynamoDbMappingException instead. Log ShardId, SequenceNumber and EventName, not the record: it holds the values of the item.

cancellationToken CancellationToken

Cancels the reading. A token given to WithCancellation works too.

Returns

IAsyncEnumerable<Change<T>>

The changes of the entity, in the order ReadStreamAsync(ReadStreamRequest, CancellationToken) returns their records.

Type Parameters

T

The entity. One without a discriminator takes every change, as As<T>() does.

Remarks

The view must be NewAndOldImages. The read is that of ReadStreamAsync<T>(Table<T>, DynamoDbStreamsClient, ShardIteratorType, TimeSpan?, Action?, CancellationToken), with its DescribeTable at the start of each enumeration, and it also checks the view there: without the old image a removal could not be typed and would be missed without a word, and without the new image an insert would. Another view throws InvalidOperationException; As<T>() types what a record of any view has.

Every change is read. A stream cannot be filtered at its source, so every change of the table is read and typed here, from the discriminator of its images, and a change of no type of the read is skipped. An item whose type changed at its key gives two changes, the removal of the old type, then the insert of the new one, each when its type is read. Arguments are checked at the call, and nothing is requested until the first change is asked for.

Exceptions

ArgumentNullException

table or streams is null.

ArgumentOutOfRangeException

shardIteratorType is neither TrimHorizon nor Latest, or emptyPageDelay is negative or 15 minutes or more.

InvalidOperationException

The table has no enabled stream, or its view is not NewAndOldImages (raised while reading).

DynamoDbMappingException

An image of a type cannot be read as it and onMappingFailure is null (raised while reading).

ResourceNotFoundException

The table does not exist (raised while reading), or what ReadStreamAsync(ReadStreamRequest, CancellationToken) throws it for.

DynamoDbException

DescribeTable fails, or the reading of the stream does, with what ReadStreamAsync(ReadStreamRequest, CancellationToken) throws, TrimmedDataAccessException among it.

OperationCanceledException

cancellationToken was cancelled.

ReadStreamAsync<T>(Table<T>, DynamoDbStreamsClient, ShardIteratorType, TimeSpan?, Action?, CancellationToken)

Reads every shard of the stream the table has now, as ReadStreamAsync(ReadStreamRequest, CancellationToken) does: orders.ReadStreamAsync(streams, ShardIteratorType.Latest, cancellationToken: ct).

public static IAsyncEnumerable<ShardChangeRecord> ReadStreamAsync<T>(this Table<T> table, DynamoDbStreamsClient streams, ShardIteratorType shardIteratorType, TimeSpan? emptyPageDelay = null, Action? onJoined = null, CancellationToken cancellationToken = default) where T : IDynamoDbDocument<T>

Parameters

table Table<T>

The table, whose client describes it.

streams DynamoDbStreamsClient

The client the stream is read with, for the same account and region as the client of the table.

shardIteratorType ShardIteratorType

Where reading starts, see ShardIteratorType.

emptyPageDelay TimeSpan?

The wait after an empty page, see EmptyPageDelay, or null for its default of one second.

onJoined Action

What is called once the reading holds a position in every shard it starts with, see OnJoined, or null.

cancellationToken CancellationToken

Cancels the reading. A token given to WithCancellation works too.

Returns

IAsyncEnumerable<ShardChangeRecord>

The records of all shards, as ReadStreamAsync(ReadStreamRequest, CancellationToken) returns them.

Type Parameters

T

How the table reads its items, which does not change the records: an image is an Item.

Remarks

Each enumeration starts with DescribeTable through Client, and reads the stream that LatestStreamArn names then. A stream that is switched off and on again is a new stream with a new ARN, so an enumeration that starts after that reads the new one; one that runs reads its stream until that ends. The table takes dynamodb:DescribeTable for this, besides the permissions of the stream.

The view of the stream is not checked: with KeysOnly a record has no image, and DescribeTableAsync(CancellationToken) tells the view, StreamViewType. Arguments are checked at the call, and nothing is requested until the first record is asked for.

Exceptions

ArgumentNullException

table or streams is null.

ArgumentOutOfRangeException

shardIteratorType is neither TrimHorizon nor Latest, or emptyPageDelay is negative or 15 minutes or more.

InvalidOperationException

The table has no enabled stream: StreamEnabled is not true, or no stream is named (raised while reading).

ResourceNotFoundException

The table does not exist (raised while reading), or what ReadStreamAsync(ReadStreamRequest, CancellationToken) throws it for.

DynamoDbException

DescribeTable fails, or the reading of the stream does, with what ReadStreamAsync(ReadStreamRequest, CancellationToken) throws, TrimmedDataAccessException among it.

OperationCanceledException

cancellationToken was cancelled.