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 */
017 package org.apache.camel;
018
019 import java.util.Map;
020 import java.util.Set;
021
022 import 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 */
034 public 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 * Returns the attachment specified by the id
245 *
246 * @param id the id under which the attachment is stored
247 * @return the data handler for this attachment or <tt>null</tt>
248 */
249 DataHandler getAttachment(String id);
250
251 /**
252 * Returns a set of attachment names of the message
253 *
254 * @return a set of attachment names
255 */
256 Set<String> getAttachmentNames();
257
258 /**
259 * Removes the attachment specified by the id
260 *
261 * @param id the id of the attachment to remove
262 */
263 void removeAttachment(String id);
264
265 /**
266 * Adds an attachment to the message using the id
267 *
268 * @param id the id to store the attachment under
269 * @param content the data handler for the attachment
270 */
271 void addAttachment(String id, DataHandler content);
272
273 /**
274 * Returns all attachments of the message
275 *
276 * @return the attachments in a map or <tt>null</tt>
277 */
278 Map<String, DataHandler> getAttachments();
279
280 /**
281 * Set all the attachments associated with this message
282 *
283 * @param attachments the attachments
284 */
285 void setAttachments(Map<String, DataHandler> attachments);
286
287 /**
288 * Returns whether this message has attachments.
289 *
290 * @return <tt>true</tt> if this message has any attachments.
291 */
292 boolean hasAttachments();
293
294 /**
295 * Returns the unique ID for a message exchange if this message is capable
296 * of creating one or <tt>null</tt> if not
297 *
298 * @return the created exchange id, or <tt>null</tt> if not capable of creating
299 * @deprecated will be removed in Camel 3.0. It is discouraged for messages to create exchange ids
300 */
301 @Deprecated
302 String createExchangeId();
303 }