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     * 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}