HeterogeneousItemConverter

An item converter which handles heterogeneous (i.e., incongruent) data types by way of a string discriminator attribute identified by typeAttribute. Each type name stored in typeAttribute identifies the delegate converter (from subConverters) used for that item.

This converter is particularly (although not solely) useful for mapping polymorphic structures. For example, given a class hierarchy:

sealed interface Vehicle

@DynamoDbItem
data class Car(
    @DynamoDbPartitionKey val id: Int,
    val manufacturer: String,
    val model: String,
    val year: Int,
) : Vehicle

@DynamoDbItem
data class Bike(
    @DynamoDbPartitionKey val id: Int,
    val manufacturer: String,
    val gears: Int,
    val isElectric: Boolean,
) : Vehicle

A heterogeneous item converter can be constructed by registering a converter for each type:

val vehicleConverter = HeterogeneousItemConverter<Vehicle>(typeAttribute = "type") {
    instanceOf("car", CarConverter)
    instanceOf("bike", BikeConverter)
}

See HeterogeneousItemConverter.Builder for details on how objects are matched to registered types.

Objects mapped in this manner will use only the attributes relevant to their specific type, plus the typeAttribute. For example, given the following items and PutItem calls:

val vehicles = listOf(
    Car(1, "Ford", "Model T", 1928),
    Bike(2, "Schwinn", 10, false),
    Car(3, "Edsel", "Corsair", 1958),
    Bike(4, "Kuwahara", 1, false),
)

val table = ... // some table which uses the vehicleConverter from above in its schema

vehicles.forEach { vehicle ->
    table.putItem(vehicle)
}

Items would be persisted in the table as:

Converters may alternatively be constructed with an explicit typeMapper function via the primary constructor. This is useful when the type name isn't determined by the object's class (e.g., when it's derived from a property value).

All conversion failures (unmapped objects, missing/non-string/unknown type attributes, and discriminator conflicts) throw IllegalArgumentException.

Type Parameters