An object which defines hooks that can execute at critical stages of the mapper request pipeline. Callers can use these hooks to observe or modify the internal steps for executing a high-level operation.

Request pipeline

The mapper request pipeline consists of 5 steps:

• Initialization: Setting up the operation pipeline and the gathering initial context

• Serialization: Converting high-level request objects (e.g., GetItemRequest) into low-level request objects (e.g., LowLevelGetItemRequest), which includes converting high-level objects to DynamoDB items consisting of attribute names and values

• Low-level invocation: Executing a low-level operation on the underlying DynamoDbClient, such as DynamoDbClient.getItem

• Deserialization: Converting low-level response objects (e.g., LowLevelGetItemResponse) into high-level response objects (e.g., GetItemResponse), which includes converting DynamoDB items consisting of attributes names and values into high-level objects

• Completion: Finalizing the high-level response to return to the caller or exception to throw

Hooks

Hooks are interceptor methods which are invoked at stages before or after specific steps in the pipeline. They come in two flavors: read-only and modify (or read-write). For example, readBeforeInvocation is a read-only hook executed in the phase before the Low-level invocation step of the pipeline.

Read-only hooks are invoked before or after each step in the pipeline (except before Initialization and after Completion). They offer a read-only view of a high-level operation in progress. They may be useful for examining the state of an operation for logging, debugging, collecting metrics, etc. Each read-only hook receives a context argument and returns Unit.

Any exception caught while executing a read-only hook will be added to the context and passed to subsequent interceptors hooks in the same phase. Only after all interceptors' read-only hooks for a given phase have completed will any exception be thrown. For example, if a mapper has two interceptors A and B registered, and A's readAfterSerialization hook throws an exception, it will be added to the context passed to B's readAfterSerialization hook. After B's readAfterSerialization hook has completed, the exception will be thrown back to the caller.

Modify hooks are invoked before each step in the pipeline (except before Initialization). They offer the ability to see and modify a high-level operation in progress. They can be used to customize behavior and data in ways that mapper configuration and item schemas do not. Each modify hook receives a context argument and returns some subset of that context as a result—either modified by the hook or passed-through from the input context.

Any exception caught while executing a modify hook will halt the execution of other interceptors' modify hooks in the same phase. The exception will be added to the context and passed to the next read-only hook. Once all interceptors' read-only hooks for that phase have finished executing the exception will be thrown. For example, if a mapper has two interceptors A and B registered, and A's modifyBeforeSerialization hook throws an exception, B's modifyBeforeSerialization hook will not be invoked. Interceptors A and B's readAfterSerialization hook will execute, after which the exception will be thrown back to the caller.

Registration and execution order

Interceptors are registered on DynamoDbMapper as configuration. Multiple interceptors may be registered on a single mapper. The order in which interceptors are given in mapper config determines the order in which they will be executed:

• For phases before the Low-level invocation step, hooks will be executed in given order

• For phases after the Low-level invocation step, hooks will be executed in reverse order

Type Parameters

Inheritors