Package org.axonframework.messaging.core

Interface Message

All Known Subinterfaces:
CommandMessage, CommandResultMessage, EventMessage, QueryMessage, QueryResponseMessage, ReplayStatusChanged, ResetContext, ResultMessage, SubscriptionQueryUpdateMessage
All Known Implementing Classes:
AbstractMessage, GenericCommandMessage, GenericCommandResultMessage, GenericEventMessage, GenericMessage, GenericQueryMessage, GenericQueryResponseMessage, GenericReplayStatusChanged, 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

      static ProcessingContext addToContext(ProcessingContext context, 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

      static @Nullable Message fromContext(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

      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

      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

      default <T> @Nullable T payloadAs(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

      default <T> @Nullable T payloadAs(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

      default <T> @Nullable T payloadAs(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

      default <T> @Nullable T payloadAs(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

      <T> @Nullable T payloadAs(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

      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

      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

      Message withMetadata(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

      Message andMetadata(Map<String,@Nullable 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

      default Message withConvertedPayload(Class<?> type, 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

      default Message withConvertedPayload(TypeReference<?> type, 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

      Message withConvertedPayload(Type type, 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.