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