Package org.axonframework.messaging.core

Interface Message

All Known Subinterfaces:
CommandMessage, CommandResultMessage, EventMessage, QueryMessage, QueryResponseMessage, ResetContext, ResultMessage, SubscriptionQueryUpdateMessage
All Known Implementing Classes:
AbstractMessage, GenericCommandMessage, GenericCommandResultMessage, GenericEventMessage, GenericMessage, GenericQueryMessage, GenericQueryResponseMessage, GenericResetContext, GenericResultMessage, GenericSubscriptionQueryUpdateMessage, MessageDecorator, TerminalEventMessage
public interface Message
Representation of a Message, containing a type, payload, and Metadata.

Typical examples of a Messages are commands, events, and queries.

Instead of implementing Message directly, consider implementing CommandMessage, EventMessage or QueryMessage instead.

Since:
2.0.0
Author:
Allard Buijze, Steven van Beelen
See Also:

  • Field Details

    • RESOURCE_KEY

      static final Context.ResourceKey<Message> RESOURCE_KEY
      The Context.ResourceKey used to store and retrieve the Message from the ProcessingContext. Should always be the message for which a handler is being called. For example, if an event handler is called within the context of a command, the message should be the event message.

  • Method Details

    • addToContext

      @Nonnull static ProcessingContext addToContext(@Nonnull ProcessingContext context, @Nonnull Message message)
      Adds the given message to the given context under the RESOURCE_KEY. This allows retrieving the message from the context later on, for example in a message handler.

      Note that as the ProcessingContext might not be mutable in all implementations, this method returns a new ProcessingContext instance which should be used in place of the original.

      Parameters:
      context - The ProcessingContext to which the message should be added.
      message - The Message to add to the context.
      Returns:
      The updated ProcessingContext with the message added under the RESOURCE_KEY.

    • fromContext

      @Nullable static Message fromContext(@Nonnull ProcessingContext context)
      Retrieves the Message from the given context using the RESOURCE_KEY.
      Parameters:
      context - The ProcessingContext from which to retrieve the Message.
      Returns:
      The Message stored in the context under the RESOURCE_KEY, or null if not found.

    • identifier

      @Nonnull String identifier()
      Returns the identifier of this Message.

      Two messages with the same identifiers should be interpreted as different representations of the same conceptual message. In such case, the metadata may be different for both representations. The payload may be identical.

      Returns:
      The unique identifier of this Message.

    • type

      @Nonnull MessageType type()
      Returns the message type of this Message.
      Returns:
      The message type of this Message.

    • payload

      @Nullable Object payload()
      Returns the payload of this Message.

      The payload is the application-specific information.

      Returns:
      The payload of this Message.

    • payloadAs

      @Nullable default <T> T payloadAs(@Nonnull Class<T> type, @Nullable Converter converter)
      Returns the payload of this Message, converted to the given type by the given converter.

      If payloadType() is assignable from the given type, payload() may be invoked instead of using the given converter.

      Implementers of this operation may optimize by storing the converted payloads, thus saving a Converter.convert(Object, Class) invocation in the process. Only when this optimization is in place will a null converter result in a successful invocation of this method.

      Type Parameters:
      T - The generic type to convert this Message's payload to.
      Parameters:
      type - The type to convert this Message's payload to.
      converter - The converter to convert this Message's payload with.
      Returns:
      The payload of this Message, converted to the given type.
      Throws:
      ConversionException - When conversion is mandatory but no converter is given.

    • payloadAs

      @Nullable default <T> T payloadAs(@Nonnull Class<T> type)
      Returns the payload of this Message casted to the given type if payloadType() is assignable from the given type, otherwise throws a ConversionException.
      Type Parameters:
      T - The generic type to convert this Message's payload to.
      Parameters:
      type - The type to convert this Message's payload to.
      Returns:
      The payload of this Message, converted to the given type.
      Throws:
      ConversionException - When the given type is not compatible with the payload type.

    • payloadAs

      @Nullable default <T> T payloadAs(@Nonnull TypeReference<T> type, @Nullable Converter converter)
      Returns the payload of this Message, converted to the given type by the given converter.

      If payloadType() is assignable from the given TypeReference.getType(), payload() may be invoked instead of using the given converter.

      Implementers of this operation may optimize by storing the converted payloads, thus saving a Converter.convert(Object, Class) invocation in the process. Only when this optimization is in place will a null converter result in a successful invocation of this method.

      Type Parameters:
      T - The generic type to convert this Message's payload to.
      Parameters:
      type - The type to convert this Message's payload to.
      converter - The converter to convert this Message's payload with.
      Returns:
      The payload of this Message, converted to the given type.
      Throws:
      ConversionException - When conversion is mandatory but no converter is given.

    • payloadAs

      @Nullable default <T> T payloadAs(@Nonnull TypeReference<T> type)
      Returns the payload of this Message casted to the given type if payloadType() is assignable from the given type, otherwise throws a ConversionException.
      Type Parameters:
      T - The generic type to convert this Message's payload to.
      Parameters:
      type - The type to convert this Message's payload to.
      Returns:
      The payload of this Message, converted to the given type.
      Throws:
      ConversionException - When the given type is not compatible with the payload type.

    • payloadAs

      @Nullable <T> T payloadAs(@Nonnull Type type, @Nullable Converter converter)
      Returns the payload of this Message, converted to the given type by the given converter.

      If the given type is an instance of Class and payloadType() is assignable from that Class, payload() may be invoked instead of using the given converter.

      Implementers of this operation may optimize by storing the converted payloads, thus saving a Converter.convert(Object, Class) invocation in the process. Only when this optimization is in place will a null converter result in a successful invocation of this method.

      Type Parameters:
      T - The generic type to convert this Message's payload to.
      Parameters:
      type - The type to convert this Message's payload to.
      converter - The converter to convert this Message's payload with.
      Returns:
      The payload of this Message, converted to the given type.
      Throws:
      ConversionException - When conversion is mandatory but no converter is given.

    • payloadType

      @Nonnull Class<?> payloadType()
      Returns the type of the payload.

      Is semantically equal to getPayload().getClass(), but allows implementations to optimize by using lazy loading or deserialization.

      Returns:
      The type of payload.

    • metadata

      @Nonnull Metadata metadata()
      Returns the Metadata for this Message.

      The Metadata is a collection of key-value pairs, where both the key and values are Strings.

      Returns:
      The Metadata for this Message.

    • withMetadata

      @Nonnull Message withMetadata(@Nonnull Map<String,String> metadata)
      Returns a copy of this Message (implementation) with the given metadata.

      All other fields, like for example the payload(), remain unchanged.

      While the implementation returned may be different from the implementation of this, implementations must take special care in returning the same type of Message to prevent errors further downstream.

      Parameters:
      metadata - The new metadata for the Message.
      Returns:
      A copy of this Message (implementation) with the given metadata.

    • andMetadata

      @Nonnull Message andMetadata(@Nonnull Map<String,String> metadata)
      Returns a copy of this Message (implementation) with its metadata merged with the given metadata.

      All other fields, like for example the payload(), remain unchanged.

      Parameters:
      metadata - The metadata to merge with.
      Returns:
      A copy of this Message (implementation) with the given metadata.

    • withConvertedPayload

      @Nonnull default Message withConvertedPayload(@Nonnull Class<?> type, @Nonnull Converter converter)
      Returns a new Message implementation with its payload() converted to the given type by the given converter. This new Message is effectively a copy of this Message with a renewed payload and payloadType().

      Will return the this instance if the payload type is assignable from the converted result.

      Parameters:
      type - The type to convert the payload() to.
      converter - The converter to convert the payload() with.
      Returns:
      A new Message implementation with its payload() converted to the given type by the given converter.
      Throws:
      ConversionException - When conversion is mandatory but no converter is given.

    • withConvertedPayload

      @Nonnull default Message withConvertedPayload(@Nonnull TypeReference<?> type, @Nonnull Converter converter)
      Returns a new Message implementation with its payload() converted to the given type by the given converter. This new Message is effectively a copy of this Message with a renewed payload and payloadType().

      Will return the this instance if the payload type is assignable from the converted result.

      Parameters:
      type - The type to convert the payload() to.
      converter - The converter to convert the payload() with.
      Returns:
      A new Message implementation with its payload() converted to the given type by the given converter.
      Throws:
      ConversionException - When conversion is mandatory but no converter is given.

    • withConvertedPayload

      @Nonnull Message withConvertedPayload(@Nonnull Type type, @Nonnull Converter converter)
      Returns a new Message implementation with its payload() converted to the given type by the given converter. This new Message is effectively a copy of this Message with a renewed payload and payloadType().

      Will return the this instance if the payload type is assignable from the converted result.

      Parameters:
      type - The type to convert the payload() to.
      converter - The converter to convert the payload() with.
      Returns:
      A new Message implementation with its payload() converted to the given type by the given converter.
      Throws:
      ConversionException - When conversion is mandatory but no converter is given.