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.List;
020    import java.util.Map;
021    
022    import org.apache.camel.spi.Synchronization;
023    import org.apache.camel.spi.UnitOfWork;
024    
025    /**
026     * An Exchange is the message container holding the information during the entire routing of
027     * a {@link  Message} received by a {@link Consumer}. 
028     * <p/>
029     * During processing down the {@link Processor} chain, the {@link Exchange} provides access to the 
030     * current (not the original) request and response {@link Message} messages. The {@link Exchange} 
031     * also holds meta-data during its entire lifetime stored as properties accessible using the 
032     * various {@link #getProperty(String)} methods. The {@link #setProperty(String, Object)} is 
033     * used to store a property. For example you can use this to store security, SLA related 
034     * data or any other information deemed useful throughout processing. If an {@link Exchange} 
035     * failed during routing the {@link Exception} that caused the failure is stored and accessible 
036     * via the {@link #getException()} method.
037     * <p/>
038     * An Exchange is created when a {@link Consumer} receives a request. A new {@link Message} is
039     * created, the request is set as the body of the {@link Message} and depending on the {@link Consumer}
040     * other {@link Endpoint} and protocol related information is added as headers on the {@link Message}.
041     * Then an Exchange is created and the newly created {@link Message} is set as the in on the Exchange.
042     * Therefore an Exchange starts its life in a {@link Consumer}. The Exchange is then sent down the
043     * {@link Route} for processing along a {@link Processor} chain. The {@link Processor} as the name
044     * suggests is what processes the {@link Message} in the Exchange and Camel, in addition to 
045     * providing out-of-the-box a large number of useful processors, it also allows you to create your own. 
046     * The rule Camel uses is to take the out {@link Message} produced by the previous {@link Processor} 
047     * and set it as the in for the next {@link Processor}. If the previous {@link Processor} did not
048     * produce an out, then the in of the previous {@link Processor} is sent as the next in. At the
049     * end of the processing chain, depending on the {@link ExchangePattern Message Exchange Pattern} (or MEP)
050     * the last out (or in of no out available) is sent by the {@link Consumer} back to the original caller.
051     * <p/>
052     * Camel, in addition to providing out-of-the-box a large number of useful processors, it also allows 
053     * you to implement and use your own. When the Exchange is passed to a {@link Processor}, it always 
054     * contains an in {@link Message} and no out {@link Message}. The {@link Processor} <b>may</b> produce 
055     * an out, depending on the nature of the {@link Processor}. The in {@link Message} can be accessed 
056     * using the {@link #getIn()} method. Since the out message is null when entering the {@link Processor}, 
057     * the {@link #getOut()} method is actually a convenient factory method that will lazily instantiate a 
058     * {@link org.apache.camel.impl.DefaultMessage} which you could populate. As an alternative you could 
059     * also instantiate your specialized  {@link Message} and set it on the exchange using the 
060     * {@link #setOut(org.apache.camel.Message)} method. Please note that a {@link Message} contains not only 
061     * the body but also headers and attachments. If you are creating a new {@link Message} the headers and 
062     * attachments of the in {@link Message} are not automatically copied to the out by Camel and you'll have 
063     * to set the headers and attachments you need yourself. If your {@link Processor} is not producing a 
064     * different {@link Message} but only needs to slightly  modify the in, you can simply update the in 
065     * {@link Message} returned by {@link #getIn()}. 
066     * <p/>
067     * See this <a href="http://camel.apache.org/using-getin-or-getout-methods-on-exchange.html">FAQ entry</a> 
068     * for more details.
069     * 
070     */
071    public interface Exchange {
072    
073        String AUTHENTICATION                   = "CamelAuthentication";
074        String AUTHENTICATION_FAILURE_POLICY_ID = "CamelAuthenticationFailurePolicyId";
075        String ACCEPT_CONTENT_TYPE              = "CamelAcceptContentType";
076        String AGGREGATED_SIZE                  = "CamelAggregatedSize";
077        String AGGREGATED_TIMEOUT               = "CamelAggregatedTimeout";
078        String AGGREGATED_COMPLETED_BY          = "CamelAggregatedCompletedBy";
079        String AGGREGATED_CORRELATION_KEY       = "CamelAggregatedCorrelationKey";
080        String AGGREGATION_STRATEGY             = "CamelAggregationStrategy";
081        String AGGREGATION_COMPLETE_ALL_GROUPS  = "CamelAggregationCompleteAllGroups";
082        String ASYNC_WAIT                       = "CamelAsyncWait";
083    
084        String BATCH_INDEX                = "CamelBatchIndex";
085        String BATCH_SIZE                 = "CamelBatchSize";
086        String BATCH_COMPLETE             = "CamelBatchComplete";
087        String BEAN_METHOD_NAME           = "CamelBeanMethodName";
088        String BEAN_MULTI_PARAMETER_ARRAY = "CamelBeanMultiParameterArray";
089        String BINDING                    = "CamelBinding";
090        // do not prefix with Camel and use lower-case starting letter as its a shared key
091        // used across other Apache products such as AMQ, SMX etc.
092        String BREADCRUMB_ID              = "breadcrumbId";
093    
094        String CHARSET_NAME      = "CamelCharsetName";
095        String CREATED_TIMESTAMP = "CamelCreatedTimestamp";
096        String CONTENT_ENCODING  = "Content-Encoding";
097        String CONTENT_LENGTH    = "Content-Length";
098        String CONTENT_TYPE      = "Content-Type";
099        String CORRELATION_ID    = "CamelCorrelationId";
100    
101        String DATASET_INDEX             = "CamelDataSetIndex";
102        String DEFAULT_CHARSET_PROPERTY  = "org.apache.camel.default.charset";
103        String DESTINATION_OVERRIDE_URL = "CamelDestinationOverrideUrl";
104        String DISABLE_HTTP_STREAM_CACHE = "CamelDisableHttpStreamCache";
105        String DUPLICATE_MESSAGE         = "CamelDuplicateMessage";
106    
107        String EXCEPTION_CAUGHT           = "CamelExceptionCaught";
108        String EVALUATE_EXPRESSION_RESULT = "CamelEvaluateExpressionResult";
109        String ERRORHANDLER_HANDLED       = "CamelErrorHandlerHandled";
110        String EXTERNAL_REDELIVERED       = "CamelExternalRedelivered";
111    
112        String FAILURE_HANDLED      = "CamelFailureHandled";
113        String FAILURE_ENDPOINT     = "CamelFailureEndpoint";
114        String FAILURE_ROUTE_ID     = "CamelFailureRouteId";
115        String FILTER_NON_XML_CHARS = "CamelFilterNonXmlChars";
116        String FILE_LOCAL_WORK_PATH = "CamelFileLocalWorkPath";
117        String FILE_NAME            = "CamelFileName";
118        String FILE_NAME_ONLY       = "CamelFileNameOnly";
119        String FILE_NAME_PRODUCED   = "CamelFileNameProduced";
120        String FILE_PATH            = "CamelFilePath";
121        String FILE_PARENT          = "CamelFileParent";
122        String FILE_LAST_MODIFIED   = "CamelFileLastModified";
123        String FILE_LENGTH          = "CamelFileLength";
124        String FILTER_MATCHED       = "CamelFilterMatched";
125        String FILE_LOCK_FILE_ACQUIRED   = "CamelFileLockFileAcquired"; 
126    
127        String GROUPED_EXCHANGE = "CamelGroupedExchange";
128        
129        String HTTP_BASE_URI           = "CamelHttpBaseUri";
130        String HTTP_CHARACTER_ENCODING = "CamelHttpCharacterEncoding";
131        String HTTP_METHOD             = "CamelHttpMethod";
132        String HTTP_PATH               = "CamelHttpPath";
133        String HTTP_PROTOCOL_VERSION   = "CamelHttpProtocolVersion";
134        String HTTP_QUERY              = "CamelHttpQuery";
135        String HTTP_RESPONSE_CODE      = "CamelHttpResponseCode";
136        String HTTP_URI                = "CamelHttpUri";
137        String HTTP_URL                = "CamelHttpUrl";
138        String HTTP_CHUNKED            = "CamelHttpChunked";
139        String HTTP_SERVLET_REQUEST    = "CamelHttpServletRequest";
140        String HTTP_SERVLET_RESPONSE   = "CamelHttpServletResponse";
141    
142        String INTERCEPTED_ENDPOINT = "CamelInterceptedEndpoint";
143        String INTERCEPT_SEND_TO_ENDPOINT_WHEN_MATCHED = "CamelInterceptSendToEndpointWhenMatched";
144    
145        String LANGUAGE_SCRIPT          = "CamelLanguageScript";
146        String LOG_DEBUG_BODY_MAX_CHARS = "CamelLogDebugBodyMaxChars";
147        String LOG_DEBUG_BODY_STREAMS   = "CamelLogDebugStreams";
148        String LOOP_INDEX               = "CamelLoopIndex";
149        String LOOP_SIZE                = "CamelLoopSize";
150    
151        String MAXIMUM_CACHE_POOL_SIZE     = "CamelMaximumCachePoolSize";
152        String MAXIMUM_ENDPOINT_CACHE_SIZE = "CamelMaximumEndpointCacheSize";
153        String MULTICAST_INDEX             = "CamelMulticastIndex";
154        String MULTICAST_COMPLETE          = "CamelMulticastComplete";
155    
156        String NOTIFY_EVENT = "CamelNotifyEvent";
157    
158        String ON_COMPLETION = "CamelOnCompletion";
159    
160        String PARENT_UNIT_OF_WORK = "CamelParentUnitOfWork";
161    
162        String RECEIVED_TIMESTAMP      = "CamelReceivedTimestamp";
163        String REDELIVERED             = "CamelRedelivered";
164        String REDELIVERY_COUNTER      = "CamelRedeliveryCounter";
165        String REDELIVERY_MAX_COUNTER  = "CamelRedeliveryMaxCounter";
166        String REDELIVERY_EXHAUSTED    = "CamelRedeliveryExhausted";
167        String REDELIVERY_DELAY        = "CamelRedeliveryDelay";
168        String ROLLBACK_ONLY           = "CamelRollbackOnly";
169        String ROLLBACK_ONLY_LAST      = "CamelRollbackOnlyLast";
170        String ROUTE_STOP              = "CamelRouteStop";
171    
172        String SOAP_ACTION        = "CamelSoapAction";
173        String SKIP_GZIP_ENCODING = "CamelSkipGzipEncoding";
174        String SLIP_ENDPOINT      = "CamelSlipEndpoint";
175        String SPLIT_INDEX        = "CamelSplitIndex";
176        String SPLIT_COMPLETE     = "CamelSplitComplete";
177        String SPLIT_SIZE         = "CamelSplitSize";
178    
179        String TIMER_COUNTER         = "CamelTimerCounter";
180        String TIMER_FIRED_TIME      = "CamelTimerFiredTime";
181        String TIMER_NAME            = "CamelTimerName";
182        String TIMER_PERIOD          = "CamelTimerPeriod";
183        String TIMER_TIME            = "CamelTimerTime";
184        String TO_ENDPOINT           = "CamelToEndpoint";
185        String TRACE_EVENT           = "CamelTraceEvent";
186        String TRACE_EVENT_NODE_ID   = "CamelTraceEventNodeId";
187        String TRACE_EVENT_TIMESTAMP = "CamelTraceEventTimestamp";
188        String TRACE_EVENT_EXCHANGE  = "CamelTraceEventExchange";
189        String TRANSFER_ENCODING     = "Transfer-Encoding";
190    
191        String UNIT_OF_WORK_EXHAUSTED    = "CamelUnitOfWorkExhausted";
192        String UNIT_OF_WORK_PROCESS_SYNC = "CamelUnitOfWorkProcessSync";
193    
194        String XSLT_FILE_NAME = "CamelXsltFileName";
195    
196        /**
197         * Returns the {@link ExchangePattern} (MEP) of this exchange.
198         *
199         * @return the message exchange pattern of this exchange
200         */
201        ExchangePattern getPattern();
202    
203        /**
204         * Allows the {@link ExchangePattern} (MEP) of this exchange to be customized.
205         *
206         * This typically won't be required as an exchange can be created with a specific MEP
207         * by calling {@link Endpoint#createExchange(ExchangePattern)} but it is here just in case
208         * it is needed.
209         *
210         * @param pattern  the pattern 
211         */
212        void setPattern(ExchangePattern pattern);
213    
214        /**
215         * Returns a property associated with this exchange by name
216         *
217         * @param name the name of the property
218         * @return the value of the given property or <tt>null</tt> if there is no property for
219         *         the given name
220         */
221        Object getProperty(String name);
222    
223        /**
224         * Returns a property associated with this exchange by name
225         *
226         * @param name the name of the property
227         * @param defaultValue the default value to return if property was absent
228         * @return the value of the given property or <tt>defaultValue</tt> if there is no
229         *         property for the given name
230         */
231        Object getProperty(String name, Object defaultValue);
232    
233        /**
234         * Returns a property associated with this exchange by name and specifying
235         * the type required
236         *
237         * @param name the name of the property
238         * @param type the type of the property
239         * @return the value of the given property or <tt>null</tt> if there is no property for
240         *         the given name or <tt>null</tt> if it cannot be converted to the given type
241         */
242        <T> T getProperty(String name, Class<T> type);
243    
244        /**
245         * Returns a property associated with this exchange by name and specifying
246         * the type required
247         *
248         * @param name the name of the property
249         * @param defaultValue the default value to return if property was absent
250         * @param type the type of the property
251         * @return the value of the given property or <tt>defaultValue</tt> if there is no property for
252         *         the given name or <tt>null</tt> if it cannot be converted to the given type
253         */
254        <T> T getProperty(String name, Object defaultValue, Class<T> type);
255    
256        /**
257         * Sets a property on the exchange
258         *
259         * @param name  of the property
260         * @param value to associate with the name
261         */
262        void setProperty(String name, Object value);
263    
264        /**
265         * Removes the given property on the exchange
266         *
267         * @param name of the property
268         * @return the old value of the property
269         */
270        Object removeProperty(String name);
271    
272        /**
273         * Returns all of the properties associated with the exchange
274         *
275         * @return all the headers in a Map
276         */
277        Map<String, Object> getProperties();
278    
279        /**
280         * Returns whether any properties has been set
281         *
282         * @return <tt>true</tt> if any properties has been set
283         */
284        boolean hasProperties();
285    
286        /**
287         * Returns the inbound request message
288         *
289         * @return the message
290         */
291        Message getIn();
292    
293        /**
294         * Returns the inbound request message as the given type
295         *
296         * @param type the given type
297         * @return the message as the given type or <tt>null</tt> if not possible to covert to given type
298         */
299        <T> T getIn(Class<T> type);
300    
301        /**
302         * Sets the inbound message instance
303         *
304         * @param in the inbound message
305         */
306        void setIn(Message in);
307    
308        /**
309         * Returns the outbound message, lazily creating one if one has not already
310         * been associated with this exchange.
311         * <p/>
312         * <br/><b>Important:</b> If you want to change the current message, then use {@link #getIn()} instead as it will
313         * ensure headers etc. is kept and propagated when routing continues. Bottom line end users should rarely use
314         * this method.
315         * <p/>
316         * <br/>If you want to test whether an OUT message have been set or not, use the {@link #hasOut()} method.
317         * <p/>
318         * See also the class java doc for this {@link Exchange} for more details and this
319         * <a href="http://camel.apache.org/using-getin-or-getout-methods-on-exchange.html">FAQ entry</a>.
320         *
321         * @return the response
322         * @see #getIn()
323         */
324        Message getOut();
325    
326        /**
327         * Returns the outbound request message as the given type
328         * <p/>
329         * <br/><b>Important:</b> If you want to change the current message, then use {@link #getIn()} instead as it will
330         * ensure headers etc. is kept and propagated when routing continues. Bottom line end users should rarely use
331         * this method.
332         * <p/>
333         * <br/>If you want to test whether an OUT message have been set or not, use the {@link #hasOut()} method.
334         * <p/>
335         * See also the class java doc for this {@link Exchange} for more details and this
336         * <a href="http://camel.apache.org/using-getin-or-getout-methods-on-exchange.html">FAQ entry</a>.
337         *
338         * @param type the given type
339         * @return the message as the given type or <tt>null</tt> if not possible to covert to given type
340         * @see #getIn(Class)
341         */
342        <T> T getOut(Class<T> type);
343    
344        /**
345         * Returns whether an OUT message has been set or not.
346         *
347         * @return <tt>true</tt> if an OUT message exists, <tt>false</tt> otherwise.
348         */
349        boolean hasOut();
350    
351        /**
352         * Sets the outbound message
353         *
354         * @param out the outbound message
355         */
356        void setOut(Message out);
357    
358        /**
359         * Returns the exception associated with this exchange
360         *
361         * @return the exception (or null if no faults)
362         */
363        Exception getException();
364    
365        /**
366         * Returns the exception associated with this exchange.
367         * <p/>
368         * Is used to get the caused exception that typically have been wrapped in some sort
369         * of Camel wrapper exception
370         * <p/>
371         * The strategy is to look in the exception hierarchy to find the first given cause that matches the type.
372         * Will start from the bottom (the real cause) and walk upwards.
373         *
374         * @param type the exception type
375         * @return the exception (or <tt>null</tt> if no caused exception matched)
376         */
377        <T> T getException(Class<T> type);
378    
379        /**
380         * Sets the exception associated with this exchange
381         * <p/>
382         * Camel will wrap {@link Throwable} into {@link Exception} type to
383         * accommodate for the {@link #getException()} method returning a plain {@link Exception} type.
384         *
385         * @param t  the caused exception
386         */
387        void setException(Throwable t);
388    
389        /**
390         * Returns true if this exchange failed due to either an exception or fault
391         *
392         * @return true if this exchange failed due to either an exception or fault
393         * @see Exchange#getException()
394         * @see Message#setFault(boolean)
395         * @see Message#isFault()
396         */
397        boolean isFailed();
398    
399        /**
400         * Returns true if this exchange is transacted
401         */
402        boolean isTransacted();
403    
404        /**
405         * Returns true if this exchange is an external initiated redelivered message (such as a JMS broker).
406         * <p/>
407         * <b>Important: </b> It is not always possible to determine if the message is a redelivery
408         * or not, and therefore <tt>null</tt> is returned. Such an example would be a JDBC message.
409         * However JMS brokers provides details if a message is redelivered.
410         *
411         * @return <tt>true</tt> if redelivered, <tt>false</tt> if not, <tt>null</tt> if not able to determine
412         */
413        Boolean isExternalRedelivered();
414    
415        /**
416         * Returns true if this exchange is marked for rollback
417         */
418        boolean isRollbackOnly();
419    
420        /**
421         * Returns the container so that a processor can resolve endpoints from URIs
422         *
423         * @return the container which owns this exchange
424         */
425        CamelContext getContext();
426    
427        /**
428         * Creates a copy of the current message exchange so that it can be
429         * forwarded to another destination
430         */
431        Exchange copy();
432    
433        /**
434         * Returns the endpoint which originated this message exchange if a consumer on an endpoint
435         * created the message exchange, otherwise this property will be <tt>null</tt>
436         */
437        Endpoint getFromEndpoint();
438    
439        /**
440         * Sets the endpoint which originated this message exchange. This method
441         * should typically only be called by {@link org.apache.camel.Endpoint} implementations
442         *
443         * @param fromEndpoint the endpoint which is originating this message exchange
444         */
445        void setFromEndpoint(Endpoint fromEndpoint);
446        
447        /**
448         * Returns the route id which originated this message exchange if a route consumer on an endpoint
449         * created the message exchange, otherwise this property will be <tt>null</tt>
450         */
451        String getFromRouteId();
452    
453        /**
454         * Sets the route id which originated this message exchange. This method
455         * should typically only be called by the internal framework.
456         *
457         * @param fromRouteId the from route id
458         */
459        void setFromRouteId(String fromRouteId);
460    
461        /**
462         * Returns the unit of work that this exchange belongs to; which may map to
463         * zero, one or more physical transactions
464         */
465        UnitOfWork getUnitOfWork();
466    
467        /**
468         * Sets the unit of work that this exchange belongs to; which may map to
469         * zero, one or more physical transactions
470         */
471        void setUnitOfWork(UnitOfWork unitOfWork);
472    
473        /**
474         * Returns the exchange id (unique)
475         */
476        String getExchangeId();
477    
478        /**
479         * Set the exchange id
480         */
481        void setExchangeId(String id);
482    
483        /**
484         * Adds a {@link org.apache.camel.spi.Synchronization} to be invoked as callback when
485         * this exchange is completed.
486         *
487         * @param onCompletion  the callback to invoke on completion of this exchange
488         */
489        void addOnCompletion(Synchronization onCompletion);
490    
491        /**
492         * Checks if the passed {@link org.apache.camel.spi.Synchronization} instance is
493         * already contained on this exchange.
494         *
495         * @param onCompletion  the callback instance that is being checked for
496         * @return <tt>true</tt>, if callback instance is already contained on this exchange, else <tt>false</tt>
497         */
498        boolean containsOnCompletion(Synchronization onCompletion);
499    
500        /**
501         * Handover all the on completions from this exchange to the target exchange.
502         *
503         * @param target the target exchange
504         */
505        void handoverCompletions(Exchange target);
506    
507        /**
508         * Handover all the on completions from this exchange
509         *
510         * @return the on completions
511         */
512        List<Synchronization> handoverCompletions();
513    
514    }