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