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 *
164 * @param headers headers to set
165 */
166 void setHeaders(Map<String, Object> headers);
167
168 /**
169 * Returns whether has any headers has been set.
170 *
171 * @return <tt>true</tt> if any headers has been set
172 */
173 boolean hasHeaders();
174
175 /**
176 * Returns the body of the message as a POJO
177 * <p/>
178 * The body can be <tt>null</tt> if no body is set
179 *
180 * @return the body, can be <tt>null</tt>
181 */
182 Object getBody();
183
184 /**
185 * Returns the body of the message as a POJO
186 *
187 * @return the body, is never <tt>null</tt>
188 * @throws InvalidPayloadException Is thrown if the body being <tt>null</tt> or wrong class type
189 */
190 Object getMandatoryBody() throws InvalidPayloadException;
191
192 /**
193 * Returns the body as the specified type
194 *
195 * @param type the type that the body
196 * @return the body of the message as the specified type, or <tt>null</tt> if no body exists
197 * @throws TypeConversionException is thrown if error during type conversion
198 */
199 <T> T getBody(Class<T> type);
200
201 /**
202 * Returns the mandatory body as the specified type
203 *
204 * @param type the type that the body
205 * @return the body of the message as the specified type, is never <tt>null</tt>.
206 * @throws InvalidPayloadException Is thrown if the body being <tt>null</tt> or wrong class type
207 */
208 <T> T getMandatoryBody(Class<T> type) throws InvalidPayloadException;
209
210 /**
211 * Sets the body of the message
212 *
213 * @param body the body
214 */
215 void setBody(Object body);
216
217 /**
218 * Sets the body of the message as a specific type
219 *
220 * @param body the body
221 * @param type the type of the body
222 */
223 <T> void setBody(Object body, Class<T> type);
224
225 /**
226 * Creates a copy of this message so that it can be used and possibly
227 * modified further in another exchange
228 *
229 * @return a new message instance copied from this message
230 */
231 Message copy();
232
233 /**
234 * Copies the contents of the other message into this message
235 *
236 * @param message the other message
237 */
238 void copyFrom(Message message);
239
240 /**
241 * Returns the attachment specified by the id
242 *
243 * @param id the id under which the attachment is stored
244 * @return the data handler for this attachment or <tt>null</tt>
245 */
246 DataHandler getAttachment(String id);
247
248 /**
249 * Returns a set of attachment names of the message
250 *
251 * @return a set of attachment names
252 */
253 Set<String> getAttachmentNames();
254
255 /**
256 * Removes the attachment specified by the id
257 *
258 * @param id the id of the attachment to remove
259 */
260 void removeAttachment(String id);
261
262 /**
263 * Adds an attachment to the message using the id
264 *
265 * @param id the id to store the attachment under
266 * @param content the data handler for the attachment
267 */
268 void addAttachment(String id, DataHandler content);
269
270 /**
271 * Returns all attachments of the message
272 *
273 * @return the attachments in a map or <tt>null</tt>
274 */
275 Map<String, DataHandler> getAttachments();
276
277 /**
278 * Set all the attachments associated with this message
279 *
280 * @param attachments the attachments
281 */
282 void setAttachments(Map<String, DataHandler> attachments);
283
284 /**
285 * Returns whether this message has attachments.
286 *
287 * @return <tt>true</tt> if this message has any attachments.
288 */
289 boolean hasAttachments();
290
291 /**
292 * Returns the unique ID for a message exchange if this message is capable
293 * of creating one or <tt>null</tt> if not
294 *
295 * @return the created exchange id, or <tt>null</tt> if not capable of creating
296 * @deprecated will be removed in Camel 3.0. It is discouraged for messages to create exchange ids
297 */
298 @Deprecated
299 String createExchangeId();
300 }