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.UnitOfWork;
022    
023    /**
024     * The base message exchange interface providing access to the request, response
025     * and fault {@link Message} instances. Different providers such as JMS, JBI,
026     * CXF and HTTP can provide their own derived API to expose the underlying
027     * transport semantics to avoid the leaky abstractions of generic APIs.
028     *
029     * @version $Revision: 752465 $
030     */
031    public interface Exchange {
032    
033        String BEAN_METHOD_NAME = "CamelBeanMethodName";
034        String BEAN_HOLDER = "CamelBeanHolder";
035        String BEAN_MULTI_PARAMETER_ARRAY = "CamelBeanMultiParameterArray";
036    
037        String AGGREGATED_SIZE = "CamelAggregatedSize";
038    
039        String CHARSET_NAME = "CamelCharsetName";
040    
041        String DATASET_INDEX = "CamelDataSetIndex";
042    
043        String EXCEPTION_CAUGHT = "CamelExceptionCaught";
044        String EXCEPTION_HANDLED = "CamelExceptionHandled";
045        String FAILURE_HANDLED = "CamelFailureHandled";
046    
047        String FILE_BATCH_INDEX = "CamelFileBatchIndex";
048        String FILE_BATCH_SIZE = "CamelFileBatchSize";
049        String FILE_LOCAL_WORK_PATH = "CamelFileLocalWorkPath";
050        String FILE_NAME = "CamelFileName";
051        String FILE_NAME_ONLY = "CamelFileNameOnly";
052        String FILE_NAME_PRODUCED = "CamelFileNameProduced";
053    
054        String LOOP_INDEX = "CamelLoopIndex";
055        String LOOP_SIZE = "CamelLoopSize";
056    
057        String PROCESSED_SYNC = "CamelProcessedSync";
058    
059        String REDELIVERED = "CamelRedelivered";
060        String REDELIVERY_COUNTER = "CamelRedeliveryCounter";
061    
062        String SPLIT_INDEX = "CamelSplitIndex";
063        String SPLIT_SIZE = "CamelSplitSize";
064    
065        String TIMER_NAME = "CamelTimerName";
066        String TIMER_FIRED_TIME = "CamelTimerFiredTime";
067        String TIMER_PERIOD = "CamelTimerPeriod";
068        String TIMER_TIME = "CamelTimerTime";
069    
070        String TRANSACTED = "CamelTransacted";
071    
072        /**
073         * Returns the {@link ExchangePattern} (MEP) of this exchange.
074         *
075         * @return the message exchange pattern of this exchange
076         */
077        ExchangePattern getPattern();
078    
079        /**
080         * Allows the {@link ExchangePattern} (MEP) of this exchange to be customized.
081         *
082         * This typically won't be required as an exchange can be created with a specific MEP
083         * by calling {@link Endpoint#createExchange(ExchangePattern)} but it is here just in case
084         * it is needed.
085         *
086         * @param pattern  the pattern 
087         */
088        void setPattern(ExchangePattern pattern);
089    
090        /**
091         * Returns a property associated with this exchange by name
092         *
093         * @param name the name of the property
094         * @return the value of the given header or null if there is no property for
095         *         the given name
096         */
097        Object getProperty(String name);
098    
099        /**
100         * Returns a property associated with this exchange by name and specifying
101         * the type required
102         *
103         * @param name the name of the property
104         * @param type the type of the property
105         * @return the value of the given header or null if there is no property for
106         *         the given name or null if it cannot be converted to the given
107         *         type
108         */
109        <T> T getProperty(String name, Class<T> type);
110    
111        /**
112         * Sets a property on the exchange
113         *
114         * @param name  of the property
115         * @param value to associate with the name
116         */
117        void setProperty(String name, Object value);
118    
119        /**
120         * Removes the given property on the exchange
121         *
122         * @param name of the property
123         * @return the old value of the property
124         */
125        Object removeProperty(String name);
126    
127        /**
128         * Returns all of the properties associated with the exchange
129         *
130         * @return all the headers in a Map
131         */
132        Map<String, Object> getProperties();
133    
134        /**
135         * Returns the inbound request message
136         *
137         * @return the message
138         */
139        Message getIn();
140    
141        /**
142         * Sets the inbound message instance
143         *
144         * @param in the inbound message
145         */
146        void setIn(Message in);
147    
148        /**
149         * Returns the outbound message, lazily creating one if one has not already
150         * been associated with this exchange. If you want to inspect this property
151         * but not force lazy creation then invoke the {@link #getOut(boolean)}
152         * method passing in <tt>false</tt>
153         *
154         * @return the response
155         */
156        Message getOut();
157    
158        /**
159         * Returns the outbound message; optionally lazily creating one if one has
160         * not been associated with this exchange
161         *
162         * @param lazyCreate <tt>true</tt> will lazy create the out message
163         * @return the response
164         */
165        Message getOut(boolean lazyCreate);
166    
167        /**
168         * Sets the outbound message
169         *
170         * @param out the outbound message
171         */
172        void setOut(Message out);
173    
174        /**
175         * Returns the fault message
176         *
177         * @return the fault
178         */
179        Message getFault();
180    
181        /**
182         * Returns the fault message; optionally lazily creating one if one has
183         * not been associated with this exchange
184         *
185         * @param lazyCreate <tt>true</tt> will lazy create the fault message
186         * @return the fault
187         */
188        Message getFault(boolean lazyCreate);
189    
190        /**
191         * Returns the exception associated with this exchange
192         *
193         * @return the exception (or null if no faults)
194         */
195        Exception getException();
196    
197        /**
198         * Sets the exception associated with this exchange
199         *
200         * @param e  the caused exception
201         */
202        void setException(Exception e);
203    
204        /**
205         * Returns true if this exchange failed due to either an exception or fault
206         *
207         * @return true if this exchange failed due to either an exception or fault
208         * @see Exchange#getException()
209         * @see Exchange#getFault()
210         */
211        boolean isFailed();
212    
213        /**
214         * Returns true if this exchange is transacted
215         */
216        boolean isTransacted();
217    
218        /**
219         * Returns the container so that a processor can resolve endpoints from URIs
220         *
221         * @return the container which owns this exchange
222         */
223        CamelContext getContext();
224    
225        /**
226         * Creates a new exchange instance with empty messages, headers and properties
227         */
228        Exchange newInstance();
229    
230        /**
231         * Creates a copy of the current message exchange so that it can be
232         * forwarded to another destination
233         */
234        Exchange copy();
235    
236        /**
237         * Copies the data into this exchange from the given exchange
238         *
239         * @param source is the source from which headers and messages will be copied
240         */
241        void copyFrom(Exchange source);
242    
243    
244        /**
245         * Returns the endpoint which originated this message exchange if a consumer on an endpoint created the message exchange
246         * otherwise this property will be null
247         */
248        Endpoint getFromEndpoint();
249    
250        /**
251         * Sets the endpoint which originated this message exchange. This method
252         * should typically only be called by {@link org.apache.camel.Endpoint} implementations
253         *
254         * @param fromEndpoint the endpoint which is originating this message exchange
255         */
256        void setFromEndpoint(Endpoint fromEndpoint);
257        
258        /**
259         * Returns the unit of work that this exchange belongs to; which may map to
260         * zero, one or more physical transactions
261         */
262        UnitOfWork getUnitOfWork();
263    
264        /**
265         * Sets the unit of work that this exchange belongs to; which may map to
266         * zero, one or more physical transactions
267         */
268        void setUnitOfWork(UnitOfWork unitOfWork);
269    
270        /**
271         * Returns the exchange id (unique)
272         */
273        String getExchangeId();
274    
275        /**
276         * Set the exchange id
277         */
278        void setExchangeId(String id);
279    
280    }