001/** 002 * Licensed to the Apache Software Foundation (ASF) under one or more 003 * contributor license agreements. See the NOTICE file distributed with 004 * this work for additional information regarding copyright ownership. 005 * The ASF licenses this file to You under the Apache License, Version 2.0 006 * (the "License"); you may not use this file except in compliance with 007 * the License. You may obtain a copy of the License at 008 * 009 * http://www.apache.org/licenses/LICENSE-2.0 010 * 011 * Unless required by applicable law or agreed to in writing, software 012 * distributed under the License is distributed on an "AS IS" BASIS, 013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 014 * See the License for the specific language governing permissions and 015 * limitations under the License. 016 */ 017package org.apache.camel; 018 019import java.util.Map; 020import java.util.Set; 021 022import javax.activation.DataHandler; 023 024/** 025 * Implements the <a 026 * href="http://camel.apache.org/message.html">Message</a> pattern and 027 * represents an inbound or outbound message as part of an {@link Exchange}. 028 * <p/> 029 * See {@link org.apache.camel.impl.DefaultMessage DefaultMessage} for how headers 030 * is represented in Camel using a {@link org.apache.camel.util.CaseInsensitiveMap CaseInsensitiveMap}. 031 * 032 * @version 033 */ 034public interface Message { 035 036 /** 037 * Returns the id of the message 038 * 039 * @return the message id 040 */ 041 String getMessageId(); 042 043 /** 044 * Sets the id of the message 045 * 046 * @param messageId id of the message 047 */ 048 void setMessageId(String messageId); 049 050 /** 051 * Returns the exchange this message is related to 052 * 053 * @return the exchange 054 */ 055 Exchange getExchange(); 056 057 /** 058 * Returns true if this message represents a fault 059 * 060 * @return <tt>true</tt> if this is a fault message, <tt>false</tt> for regular messages. 061 */ 062 boolean isFault(); 063 064 /** 065 * Sets the fault flag on this message 066 * 067 * @param fault the fault flag 068 */ 069 void setFault(boolean fault); 070 071 /** 072 * Accesses a specific header 073 * 074 * @param name name of header 075 * @return the value of the given header or <tt>null</tt> if there is no 076 * header for the given name 077 */ 078 Object getHeader(String name); 079 080 /** 081 * Accesses a specific header 082 * 083 * @param name name of header 084 * @param defaultValue the default value to return if header was absent 085 * @return the value of the given header or <tt>defaultValue</tt> if there is no 086 * header for the given name 087 */ 088 Object getHeader(String name, Object defaultValue); 089 090 /** 091 * Returns a header associated with this message by name and specifying the 092 * type required 093 * 094 * @param name the name of the header 095 * @param type the type of the header 096 * @return the value of the given header or <tt>null</tt> if there is no header for 097 * the given name 098 * @throws TypeConversionException is thrown if error during type conversion 099 */ 100 <T> T getHeader(String name, Class<T> type); 101 102 /** 103 * Returns a header associated with this message by name and specifying the 104 * type required 105 * 106 * @param name the name of the header 107 * @param defaultValue the default value to return if header was absent 108 * @param type the type of the header 109 * @return the value of the given header or <tt>defaultValue</tt> if there is no header for 110 * the given name or <tt>null</tt> if it cannot be converted to the given type 111 */ 112 <T> T getHeader(String name, Object defaultValue, Class<T> type); 113 114 /** 115 * Sets a header on the message 116 * 117 * @param name of the header 118 * @param value to associate with the name 119 */ 120 void setHeader(String name, Object value); 121 122 /** 123 * Removes the named header from this message 124 * 125 * @param name name of the header 126 * @return the old value of the header 127 */ 128 Object removeHeader(String name); 129 130 /** 131 * Removes the headers from this message 132 * 133 * @param pattern pattern of names 134 * @return boolean whether any headers matched 135 */ 136 boolean removeHeaders(String pattern); 137 138 /** 139 * Removes the headers from this message that match the given <tt>pattern</tt>, 140 * except for the ones matching one ore more <tt>excludePatterns</tt> 141 * 142 * @param pattern pattern of names that should be removed 143 * @param excludePatterns one or more pattern of header names that should be excluded (= preserved) 144 * @return boolean whether any headers matched 145 */ 146 boolean removeHeaders(String pattern, String... excludePatterns); 147 148 /** 149 * Returns all of the headers associated with the message. 150 * <p/> 151 * See {@link org.apache.camel.impl.DefaultMessage DefaultMessage} for how headers 152 * is represented in Camel using a {@link org.apache.camel.util.CaseInsensitiveMap CaseInsensitiveMap}. 153 * <p/> 154 * <b>Important:</b> If you want to walk the returned {@link Map} and fetch all the keys and values, you should use 155 * the {@link java.util.Map#entrySet()} method, which ensure you get the keys in the original case. 156 * 157 * @return all the headers in a Map 158 */ 159 Map<String, Object> getHeaders(); 160 161 /** 162 * Set all the headers associated with this message 163 * <p/> 164 * <b>Important:</b> If you want to copy headers from another {@link Message} to this {@link Message}, then 165 * use <tt>getHeaders().putAll(other)</tt> to copy the headers, where <tt>other</tt> is the other headers. 166 * 167 * @param headers headers to set 168 */ 169 void setHeaders(Map<String, Object> headers); 170 171 /** 172 * Returns whether has any headers has been set. 173 * 174 * @return <tt>true</tt> if any headers has been set 175 */ 176 boolean hasHeaders(); 177 178 /** 179 * Returns the body of the message as a POJO 180 * <p/> 181 * The body can be <tt>null</tt> if no body is set 182 * 183 * @return the body, can be <tt>null</tt> 184 */ 185 Object getBody(); 186 187 /** 188 * Returns the body of the message as a POJO 189 * 190 * @return the body, is never <tt>null</tt> 191 * @throws InvalidPayloadException Is thrown if the body being <tt>null</tt> or wrong class type 192 */ 193 Object getMandatoryBody() throws InvalidPayloadException; 194 195 /** 196 * Returns the body as the specified type 197 * 198 * @param type the type that the body 199 * @return the body of the message as the specified type, or <tt>null</tt> if no body exists 200 * @throws TypeConversionException is thrown if error during type conversion 201 */ 202 <T> T getBody(Class<T> type); 203 204 /** 205 * Returns the mandatory body as the specified type 206 * 207 * @param type the type that the body 208 * @return the body of the message as the specified type, is never <tt>null</tt>. 209 * @throws InvalidPayloadException Is thrown if the body being <tt>null</tt> or wrong class type 210 */ 211 <T> T getMandatoryBody(Class<T> type) throws InvalidPayloadException; 212 213 /** 214 * Sets the body of the message 215 * 216 * @param body the body 217 */ 218 void setBody(Object body); 219 220 /** 221 * Sets the body of the message as a specific type 222 * 223 * @param body the body 224 * @param type the type of the body 225 */ 226 <T> void setBody(Object body, Class<T> type); 227 228 /** 229 * Creates a copy of this message so that it can be used and possibly 230 * modified further in another exchange 231 * 232 * @return a new message instance copied from this message 233 */ 234 Message copy(); 235 236 /** 237 * Copies the contents of the other message into this message 238 * 239 * @param message the other message 240 */ 241 void copyFrom(Message message); 242 243 /** 244 * Copies the attachments of the other message into this message 245 * 246 * @param message the other message 247 */ 248 void copyAttachments(Message message); 249 250 /** 251 * Returns the attachment specified by the id 252 * 253 * @param id the id under which the attachment is stored 254 * @return the data handler for this attachment or <tt>null</tt> 255 */ 256 DataHandler getAttachment(String id); 257 258 /** 259 * Returns a set of attachment names of the message 260 * 261 * @return a set of attachment names 262 */ 263 Set<String> getAttachmentNames(); 264 265 /** 266 * Removes the attachment specified by the id 267 * 268 * @param id the id of the attachment to remove 269 */ 270 void removeAttachment(String id); 271 272 /** 273 * Adds an attachment to the message using the id 274 * 275 * @param id the id to store the attachment under 276 * @param content the data handler for the attachment 277 */ 278 void addAttachment(String id, DataHandler content); 279 280 /** 281 * Returns all attachments of the message 282 * 283 * @return the attachments in a map or <tt>null</tt> 284 */ 285 Map<String, DataHandler> getAttachments(); 286 287 /** 288 * Set all the attachments associated with this message 289 * 290 * @param attachments the attachments 291 */ 292 void setAttachments(Map<String, DataHandler> attachments); 293 294 /** 295 * Returns whether this message has attachments. 296 * 297 * @return <tt>true</tt> if this message has any attachments. 298 */ 299 boolean hasAttachments(); 300 301 /** 302 * Returns the unique ID for a message exchange if this message is capable 303 * of creating one or <tt>null</tt> if not 304 * 305 * @return the created exchange id, or <tt>null</tt> if not capable of creating 306 * @deprecated will be removed in Camel 3.0. It is discouraged for messages to create exchange ids 307 */ 308 @Deprecated 309 String createExchangeId(); 310}