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