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
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 theInvalidPayloadExceptionexception 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, returnnull.
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<String, Object> map) { 6 // Initialize headers from underlying message (lazy creation). } @Override protected void populateInitialAttachments(Map<String, DataHandler> map) { 7 // Initialize attachments from underlying message (lazy creation). } }
- 1
- Implements a custom message class, CustomMessage, by extending the
org.apache.camel.impl.DefaultMessageclass. - 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 theMessageSupport.copy()method. Customization of thenewInstance()method should focus on copying all of the custom properties of the current message instance into the new message instance. TheMessageSupport.copy()method copies the generic message properties by callingcopyFrom(). - 5
- The
createBody()method works in conjunction with theMessageSupport.getBody()method to implement lazy access to the message body. By default, the message body isnull. It is only when the application code tries to access the body (by callinggetBody()), that the body should be created. TheMessageSupport.getBody()automatically callscreateBody(), 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. ThepopulateInitialHeaders()method is automatically called when a user attempts to access a header (or headers) for the first time (by callinggetHeader(),getHeaders(),setHeader(), orsetHeaders()). - 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. ThepopulateInitialAttachments()method is automatically called when a user attempts to access an attachment (or attachments) for the first time by callinggetAttachment(),getAttachments(),getAttachmentNames(), oraddAttachment().
