Chapter 44. Message Interface

Abstract

This chapter describes how to implement the Message interface, which is an optional step in the implementation of a Apache Camel component.

44.1. The Message Interface

Overview

An instance of org.apache.camel.Message type can represent any kind of message (In or Out). Figure 44.1, “Message Inheritance Hierarchy” shows the inheritance hierarchy for the message type. You do not always need to implement a custom message type for a component. In many cases, the default implementation, DefaultMessage, is adequate.

Figure 44.1. Message Inheritance Hierarchy

Message inheritance hierarchy

The Message interface

Example 44.1, “Message Interface” shows the definition of the org.apache.camel.Message interface.

Example 44.1. Message Interface

package org.apache.camel;

import java.util.Map;
import java.util.Set;

import javax.activation.DataHandler;

public interface Message {

    String getMessageId();
    void setMessageId(String messageId);

    Exchange getExchange();

    boolean isFault();
    void    setFault(boolean fault);

    Object getHeader(String name);
    Object getHeader(String name, Object defaultValue);
    <T> T getHeader(String name, Class<T> type);
    <T> T getHeader(String name, Object defaultValue, Class<T> type);
    Map<String, Object> getHeaders();
    void setHeader(String name, Object value);
    void setHeaders(Map<String, Object> headers);
    Object  removeHeader(String name);
    boolean removeHeaders(String pattern);
    boolean hasHeaders();

    Object getBody();
    Object getMandatoryBody() throws InvalidPayloadException;
    <T> T  getBody(Class<T> type);
    <T> T  getMandatoryBody(Class<T> type) throws InvalidPayloadException;
    void     setBody(Object body);
    <T> void setBody(Object body, Class<T> type);

    DataHandler getAttachment(String id);
    Map<String, DataHandler> getAttachments();
    Set<String> getAttachmentNames();
    void removeAttachment(String id);
    void addAttachment(String id, DataHandler content);
    void setAttachments(Map<String, DataHandler> attachments);
    boolean hasAttachments();

    Message copy();

    void copyFrom(Message message);

    String createExchangeId();
}

Message methods

The Message interface defines the following methods:

  • setMessageId(), getMessageId() — Getter and setter methods for the message ID. Whether or not you need to use a message ID in your custom component is an implementation detail.
  • getExchange() — Returns a reference to the parent exchange object.
  • isFault(), setFault() — Getter and setter methods for the fault flag, which indicates whether or not this message is a fault message.
  • getHeader(), getHeaders(), setHeader(), setHeaders(), removeHeader(), hasHeaders() — Getter and setter methods for the message headers. In general, these message headers can be used either to store actual header data, or to store miscellaneous metadata.
  • getBody(), getMandatoryBody(), setBody() — Getter and setter methods for the message body. The getMandatoryBody() accessor guarantees that the returned body is non-null, otherwise the InvalidPayloadException exception is thrown.
  • getAttachment(), getAttachments(), getAttachmentNames(), removeAttachment(), addAttachment(), setAttachments(), hasAttachments() — Methods to get, set, add, and remove attachments.
  • copy() — Creates a new, identical (including the message ID) copy of the current custom message object.
  • copyFrom() — Copies the complete contents (including the message ID) of the specified generic message object, message, into the current message instance. Because this method must be able to copy from any message type, it copies the generic message properties, but not the custom properties.
  • createExchangeId() — Returns the unique ID for this exchange, if the message implementation is capable of providing an ID; otherwise, return null.

44.2. Implementing the Message Interface

How to implement a custom message

Example 44.2, “Custom Message Implementation” outlines how to implement a message by extending the DefaultMessage class.

Example 44.2. Custom Message Implementation

import org.apache.camel.Exchange;
import org.apache.camel.impl.DefaultMessage;

public class CustomMessage extends DefaultMessage { 1

    public CustomMessage() { 2
        // Create message with default properties...
    }

    @Override
    public String toString() { 3
        // Return a stringified message...
    }

    @Override
    public CustomMessage newInstance() { 4
        return new CustomMessage( ... );
    }

    @Override
    protected Object createBody() { 5
        // Return message body (lazy creation).
    }

    @Override
    protected void populateInitialHeaders(Map&lt;String, Object&gt; map) { 6
        // Initialize headers from underlying message (lazy creation).
    }

    @Override
    protected void populateInitialAttachments(Map&lt;String, DataHandler&gt; map) { 7
        // Initialize attachments from underlying message (lazy creation).
    }
}
1
Implements a custom message class, CustomMessage, by extending the org.apache.camel.impl.DefaultMessage class.
2
Typically, you need a default constructor that creates a message with default properties.
3
Override the toString() method to customize message stringification.
4
The newInstance() method is called from inside the MessageSupport.copy() method. Customization of the newInstance() method should focus on copying all of the custom properties of the current message instance into the new message instance. The MessageSupport.copy() method copies the generic message properties by calling copyFrom().
5
The createBody() method works in conjunction with the MessageSupport.getBody() method to implement lazy access to the message body. By default, the message body is null. It is only when the application code tries to access the body (by calling getBody()), that the body should be created. The MessageSupport.getBody() automatically calls createBody(), when the message body is accessed for the first time.
6
The populateInitialHeaders() method works in conjunction with the header getter and setter methods to implement lazy access to the message headers. This method parses the message to extract any message headers and inserts them into the hash map, map. The populateInitialHeaders() method is automatically called when a user attempts to access a header (or headers) for the first time (by calling getHeader(), getHeaders(), setHeader(), or setHeaders()).
7
The populateInitialAttachments() method works in conjunction with the attachment getter and setter methods to implement lazy access to the attachments. This method extracts the message attachments and inserts them into the hash map, map. The populateInitialAttachments() method is automatically called when a user attempts to access an attachment (or attachments) for the first time by calling getAttachment(), getAttachments(), getAttachmentNames(), or addAttachment().