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
021 import org.apache.camel.spi.Synchronization;
022 import org.apache.camel.spi.UnitOfWork;
023
024 /**
025 * The base message exchange interface providing access to the request, response
026 * and fault {@link Message} instances. Different providers such as JMS, JBI,
027 * CXF and HTTP can provide their own derived API to expose the underlying
028 * transport semantics to avoid the leaky abstractions of generic APIs.
029 *
030 * @version $Revision: 783663 $
031 */
032 public interface Exchange {
033
034 String AGGREGATED_INDEX = "CamelAggregatedIndex";
035 String AGGREGATED_SIZE = "CamelAggregatedSize";
036
037 String ASYNC_WAIT = "CamelAsyncWait";
038
039 String BATCH_INDEX = "CamelBatchIndex";
040 String BATCH_SIZE = "CamelBatchSize";
041 String BATCH_COMPLETE = "CamelBatchComplete";
042
043 String BEAN_METHOD_NAME = "CamelBeanMethodName";
044 String BEAN_HOLDER = "CamelBeanHolder";
045 String BEAN_MULTI_PARAMETER_ARRAY = "CamelBeanMultiParameterArray";
046
047 String CHARSET_NAME = "CamelCharsetName";
048 String CONTENT_TYPE = "CamelContentType";
049
050 String DATASET_INDEX = "CamelDataSetIndex";
051
052 String EXCEPTION_CAUGHT = "CamelExceptionCaught";
053 String EXCEPTION_HANDLED = "CamelExceptionHandled";
054 String FAILURE_HANDLED = "CamelFailureHandled";
055
056 String FILE_LOCAL_WORK_PATH = "CamelFileLocalWorkPath";
057 String FILE_NAME = "CamelFileName";
058 String FILE_NAME_ONLY = "CamelFileNameOnly";
059 String FILE_NAME_PRODUCED = "CamelFileNameProduced";
060 String FILE_PATH = "CamelFilePath";
061 String FILE_PARENT = "CamelFileParent";
062 String FILTERED = "CamelFiltered";
063
064 String HTTP_CHARACTER_ENCODING = "CamelHttpCharacterEncoding";
065 String HTTP_METHOD = "CamelHttpMethod";
066 String HTTP_PATH = "CamelHttpPath";
067 String HTTP_QUERY = "CamelHttpQuery";
068 String HTTP_RESPONSE_CODE = "CamelHttpResponseCode";
069 String HTTP_URI = "CamelHttpUri";
070
071 String INTERCEPTED_ENDPOINT = "CamelInterceptedEndpoint";
072
073 String LOG_DEBUG_BODY_MAX_CHARS = "CamelLogDebugBodyMaxChars";
074 String LOOP_INDEX = "CamelLoopIndex";
075 String LOOP_SIZE = "CamelLoopSize";
076
077 String MULTICAST_INDEX = "CamelMulticastIndex";
078
079 String ON_COMPLETION = "CamelOnCompletion";
080
081 String ROUTE_STOP = "CamelRouteStop";
082
083 String REDELIVERED = "CamelRedelivered";
084 String REDELIVERY_COUNTER = "CamelRedeliveryCounter";
085
086 String SPLIT_INDEX = "CamelSplitIndex";
087 String SPLIT_SIZE = "CamelSplitSize";
088
089 String TIMER_FIRED_TIME = "CamelTimerFiredTime";
090 String TIMER_NAME = "CamelTimerName";
091 String TIMER_PERIOD = "CamelTimerPeriod";
092 String TIMER_TIME = "CamelTimerTime";
093
094 String TRANSACTED = "CamelTransacted";
095 String ROLLBACK_ONLY = "CamelRollbackOnly";
096
097 /**
098 * Returns the {@link ExchangePattern} (MEP) of this exchange.
099 *
100 * @return the message exchange pattern of this exchange
101 */
102 ExchangePattern getPattern();
103
104 /**
105 * Allows the {@link ExchangePattern} (MEP) of this exchange to be customized.
106 *
107 * This typically won't be required as an exchange can be created with a specific MEP
108 * by calling {@link Endpoint#createExchange(ExchangePattern)} but it is here just in case
109 * it is needed.
110 *
111 * @param pattern the pattern
112 */
113 void setPattern(ExchangePattern pattern);
114
115 /**
116 * Returns a property associated with this exchange by name
117 *
118 * @param name the name of the property
119 * @return the value of the given header or null if there is no property for
120 * the given name
121 */
122 Object getProperty(String name);
123
124 /**
125 * Returns a property associated with this exchange by name and specifying
126 * the type required
127 *
128 * @param name the name of the property
129 * @param type the type of the property
130 * @return the value of the given header or null if there is no property for
131 * the given name or null if it cannot be converted to the given
132 * type
133 */
134 <T> T getProperty(String name, Class<T> type);
135
136 /**
137 * Sets a property on the exchange
138 *
139 * @param name of the property
140 * @param value to associate with the name
141 */
142 void setProperty(String name, Object value);
143
144 /**
145 * Removes the given property on the exchange
146 *
147 * @param name of the property
148 * @return the old value of the property
149 */
150 Object removeProperty(String name);
151
152 /**
153 * Returns all of the properties associated with the exchange
154 *
155 * @return all the headers in a Map
156 */
157 Map<String, Object> getProperties();
158
159 /**
160 * Returns the inbound request message
161 *
162 * @return the message
163 */
164 Message getIn();
165
166 /**
167 * Sets the inbound message instance
168 *
169 * @param in the inbound message
170 */
171 void setIn(Message in);
172
173 /**
174 * Returns the outbound message, lazily creating one if one has not already
175 * been associated with this exchange.
176 * <p/>
177 * If you want to test whether an OUT message have been set or not, use the {@link #hasOut()} method.
178 *
179 * @return the response
180 */
181 Message getOut();
182
183 /**
184 * Returns whether an OUT message has been set or not.
185 *
186 * @return <tt>true</tt> if an OUT message exists, <tt>false</tt> otherwise.
187 */
188 boolean hasOut();
189
190 /**
191 * Returns the outbound message; optionally lazily creating one if one has
192 * not been associated with this exchange
193 *
194 * @param lazyCreate <tt>true</tt> will lazy create the out message
195 * @return the response
196 * @deprecated use {@link #hasOut()} or {@link #getOut()}. Will be remove in Camel 2.0 GA.
197 */
198 Message getOut(boolean lazyCreate);
199
200 /**
201 * Sets the outbound message
202 *
203 * @param out the outbound message
204 */
205 void setOut(Message out);
206
207 /**
208 * Returns the fault message
209 *
210 * @return the fault
211 */
212 Message getFault();
213
214 /**
215 * Returns whether a FAULT message has been set or not.
216 *
217 * @return <tt>true</tt> if a FAULT message exists, <tt>false</tt> otherwise.
218 */
219 boolean hasFault();
220
221 /**
222 * Returns the fault message; optionally lazily creating one if one has
223 * not been associated with this exchange
224 *
225 * @param lazyCreate <tt>true</tt> will lazy create the fault message
226 * @return the fault
227 * @deprecated use {@link #hasFault()} or {@link #getFault()}. Will be remove in Camel 2.0 GA.
228 */
229 Message getFault(boolean lazyCreate);
230
231 /**
232 * Removes the fault message.
233 */
234 void removeFault();
235
236 /**
237 * Returns the exception associated with this exchange
238 *
239 * @return the exception (or null if no faults)
240 */
241 Exception getException();
242
243 /**
244 * Returns the exception associated with this exchange.
245 * <p/>
246 * Is used to get the caused exception that typically have been wrapped in some sort
247 * of Camel wrapper exception
248 * <p/>
249 * The stategy is to look in the exception hieracy to find the first given cause that matches the type.
250 * Will start from the bottom (the real cause) and walk upwards.
251 *
252 * @param type the exception type
253 * @return the exception (or null if no faults or if no caused exception matched)
254 */
255 <T> T getException(Class<T> type);
256
257 /**
258 * Sets the exception associated with this exchange
259 *
260 * @param e the caused exception
261 */
262 void setException(Exception e);
263
264 /**
265 * Returns true if this exchange failed due to either an exception or fault
266 *
267 * @return true if this exchange failed due to either an exception or fault
268 * @see Exchange#getException()
269 * @see Exchange#getFault()
270 */
271 boolean isFailed();
272
273 /**
274 * Returns true if this exchange is transacted
275 */
276 boolean isTransacted();
277
278 /**
279 * Returns true if this exchange is marked for rollback
280 */
281 boolean isRollbackOnly();
282
283 /**
284 * Returns the container so that a processor can resolve endpoints from URIs
285 *
286 * @return the container which owns this exchange
287 */
288 CamelContext getContext();
289
290 /**
291 * Creates a new exchange instance with empty messages, headers and properties
292 */
293 Exchange newInstance();
294
295 /**
296 * Creates a copy of the current message exchange so that it can be
297 * forwarded to another destination
298 */
299 Exchange copy();
300
301 /**
302 * Creates a new instance and copies from the current message exchange so that it can be
303 * forwarded to another destination as a new instance. Unlike regular copy this operation
304 * will not share the same {@link org.apache.camel.spi.UnitOfWork} so its should be used
305 * for async messaging, where the original and copied exchange are independent.
306 *
307 * @param handoverOnCompletion whether the on completion callbacks should be handed over to the new copy.
308 */
309 Exchange newCopy(boolean handoverOnCompletion);
310
311 /**
312 * Copies the data into this exchange from the given exchange
313 *
314 * @param source is the source from which headers and messages will be copied
315 */
316 void copyFrom(Exchange source);
317
318 /**
319 * Returns the endpoint which originated this message exchange if a consumer on an endpoint created the message exchange
320 * otherwise this property will be null
321 */
322 Endpoint getFromEndpoint();
323
324 /**
325 * Sets the endpoint which originated this message exchange. This method
326 * should typically only be called by {@link org.apache.camel.Endpoint} implementations
327 *
328 * @param fromEndpoint the endpoint which is originating this message exchange
329 */
330 void setFromEndpoint(Endpoint fromEndpoint);
331
332 /**
333 * Returns the unit of work that this exchange belongs to; which may map to
334 * zero, one or more physical transactions
335 */
336 UnitOfWork getUnitOfWork();
337
338 /**
339 * Sets the unit of work that this exchange belongs to; which may map to
340 * zero, one or more physical transactions
341 */
342 void setUnitOfWork(UnitOfWork unitOfWork);
343
344 /**
345 * Returns the exchange id (unique)
346 */
347 String getExchangeId();
348
349 /**
350 * Set the exchange id
351 */
352 void setExchangeId(String id);
353
354 /**
355 * Adds a {@link org.apache.camel.spi.Synchronization} to be invoked as callback when
356 * this exchange is completed.
357 *
358 * @param onCompletion the callback to invoke on completion of this exchange
359 */
360 void addOnCompletion(Synchronization onCompletion);
361
362 }