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