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    }