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: 20271 $
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    }