de.otto.synapse.message

Interface Key

All Superinterfaces:

java.io.Serializable

All Known Implementing Classes:

CompoundKey, SimpleKey

public interface Key
extends java.io.Serializable

The Key of a Message.

Message keys are used for different purposes:

• As identifiers for entities stored in a StateRepository, database or other kind of repository.
• For filtering messages, for example, using MessageConsumer.keyPattern(), EventSourceConsumer.keyPattern() or MessageQueueConsumer.keyPattern().
• To select the partition (aka shard) used to send the message: All messages with the same partitionKey() will be sent over the same partiion, so the ordering of theses messages can be guaranteed.
• To specify a key used for compaction purposes: Message compaction will reduce all messages with the same compactionKey() to the last message. The compacted sequence of messages is stored in a MessageStore and used by EventSource to reduce startup times of services.

Example:

A channel with product-update events is partitioned into two shards A and B. Product update events are separated into ProductUpdated, PriceUpdated or AvailabilityUpdated. We need to keep the ordering of all messages per product. Given some variable productId, we could sent messages using the following keys:

• ProductUpdated: Key.of(productId, "ProductUpdated#" + productId)
• PriceUpdated: Key.of(productId, "PriceUpdated#" + productId)
• AvailabilityUpdated: Key.of(productId, "AvailabilityUpdated#" + productId)

Using the productid (or entity id) as a partition key will guarantee that all events of the same product will arrive at the same partition or shard, in the same order as they were sent.

The event-type in combination with the entity-id as a compaction key will guarantee, that after a compaction, the latest events for product-, price- and availability-updates are available in the compacted snapshot.

Field Summary

Fields

Modifier and Type	Field and Description
static Key	NO_KEY Key used for messages that do not have a distinguished key.

Method Summary

Modifier and Type	Method and Description
java.lang.String	compactionKey() Returns the part of the key that is used for message compaction, where a snapshot of a message log is taken by only keeping the latest message for every compaction-key.
static Key	of() Key used for messages that do not have a distinguished key.
static Key	of(java.lang.String key) Creates a simple Key where the same string is used for partitioning and compaction purposes.
static Key	of(java.lang.String partitionKey, java.lang.String compactionKey) Creates a compound Key, consisting of separate partion- and compaction-keys.
java.lang.String	partitionKey() Returns the part of the key that is used to select one of possibly several shards or partitions of a message channel.

Field Detail

NO_KEY

static final Key NO_KEY

Key used for messages that do not have a distinguished key.

Note, that all messages w/o key might be sent over the same partition/shard.

Method Detail

of

static Key of()

Key used for messages that do not have a distinguished key.

Note, that all messages w/o key might be sent over the same partition/shard.

Returns:

NO_KEY

of

static Key of(@Nonnull
              java.lang.String key)

Creates a simple Key where the same string is used for partitioning and compaction purposes.

Simple keys are applicable if only a single kind of messages is sent over the channel. In this case, the id of the logical entity (like, for example, the product-id) is a good candidate for building keys.

If the channel is sharded and different kind of messages like price-updates and availability-updates will be sent over the same channel, and if the channel is compacted, of(String, String) must be used, otherwise data-loss after compaction, or out-of-order arrival of messages will most likely be the result.

Parameters:

key - the message key

Returns:

SimpleKey

of

static Key of(@Nonnull
              java.lang.String partitionKey,
              @Nonnull
              java.lang.String compactionKey)

Creates a compound Key, consisting of separate partion- and compaction-keys.

Compound keys must be used instead of simple keys if different event-types will be sent of a partitioned channel.

Parameters:

partitionKey - the part of the key that is used to select the partition of a channel when sending messages. In most cases, an entity-id like, for example, a product-id is appropriate.

compactionKey - the part of the key that is used for compaction purposes. A combination of event-type and entity-id will do the job.

Returns:

CompoundKey

partitionKey

@Nonnull
java.lang.String partitionKey()

Returns the part of the key that is used to select one of possibly several shards or partitions of a message channel.

All messages with the same partitionKey are guaranteed to keep their ordering.

Returns:

partition key

compactionKey

@Nonnull
java.lang.String compactionKey()

Returns the part of the key that is used for message compaction, where a snapshot of a message log is taken by only keeping the latest message for every compaction-key.

Returns:

compaction key