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