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: 673008 $
030     */
031    public interface Exchange {
032        
033        /**
034         * Returns the {@link ExchangePattern} (MEP) of this exchange.
035         *
036         * @return the message exchange pattern of this exchange
037         */
038        ExchangePattern getPattern();
039    
040        /**
041         * Allows the {@link ExchangePattern} (MEP) of this exchange to be customized.
042         *
043         * This typically won't be required as an exchange can be created with a specific MEP
044         * by calling {@link Endpoint#createExchange(ExchangePattern)} but it is here just in case
045         * it is needed.
046         */
047        void setPattern(ExchangePattern pattern);
048    
049        /**
050         * Returns a property associated with this exchange by name
051         *
052         * @param name the name of the property
053         * @return the value of the given header or null if there is no property for
054         *         the given name
055         */
056        Object getProperty(String name);
057    
058        /**
059         * Returns a property associated with this exchange by name and specifying
060         * the type required
061         *
062         * @param name the name of the property
063         * @param type the type of the property
064         * @return the value of the given header or null if there is no property for
065         *         the given name or null if it cannot be converted to the given
066         *         type
067         */
068        <T> T getProperty(String name, Class<T> type);
069    
070        /**
071         * Sets a property on the exchange
072         *
073         * @param name  of the property
074         * @param value to associate with the name
075         */
076        void setProperty(String name, Object value);
077    
078        /**
079         * Removes the given property on the exchange
080         *
081         * @param name of the property
082         * @return the old value of the property
083         */
084        Object removeProperty(String name);
085    
086        /**
087         * Returns all of the properties associated with the exchange
088         *
089         * @return all the headers in a Map
090         */
091        Map<String, Object> getProperties();
092    
093        /**
094         * Returns the inbound request message
095         *
096         * @return the message
097         */
098        Message getIn();
099    
100        /**
101         * Sets the inbound message instance
102         *
103         * @param in the inbound message
104         */
105        void setIn(Message in);
106    
107        /**
108         * Returns the outbound message, lazily creating one if one has not already
109         * been associated with this exchange. If you want to inspect this property
110         * but not force lazy creation then invoke the {@link #getOut(boolean)}
111         * method passing in <tt>false</tt>
112         *
113         * @return the response
114         */
115        Message getOut();
116    
117        /**
118         * Returns the outbound message; optionally lazily creating one if one has
119         * not been associated with this exchange
120         *
121         * @return the response
122         */
123        Message getOut(boolean lazyCreate);
124    
125        /**
126         * Sets the outbound message
127         *
128         * @param out the outbound message
129         */
130        void setOut(Message out);
131    
132        /**
133         * Returns the fault message
134         *
135         * @return the fault
136         */
137        Message getFault();
138    
139        /**
140         * Returns the fault message; optionally lazily creating one if one has
141         * not been associated with this exchange
142         *
143         * @param lazyCreate <tt>true</tt> will lazy create the fault message
144         *
145         * @return the fault
146         */
147        Message getFault(boolean lazyCreate);
148    
149        /**
150         * Returns the exception associated with this exchange
151         *
152         * @return the exception (or null if no faults)
153         */
154        Throwable getException();
155    
156        /**
157         * Sets the exception associated with this exchange
158         *
159         * @param e  the caused exception
160         */
161        void setException(Throwable e);
162    
163        /**
164         * Returns true if this exchange failed due to either an exception or fault
165         *
166         * @return true if this exchange failed due to either an exception or fault
167         * @see Exchange#getException()
168         * @see Exchange#getFault()
169         */
170        boolean isFailed();
171    
172        /**
173         * Returns true if this exchange is transacted
174         */
175        boolean isTransacted();
176        
177        /**
178         * Returns the container so that a processor can resolve endpoints from URIs
179         *
180         * @return the container which owns this exchange
181         */
182        CamelContext getContext();
183    
184        /**
185         * Creates a new exchange instance with empty messages, headers and properties
186         */
187        Exchange newInstance();
188    
189        /**
190         * Creates a copy of the current message exchange so that it can be
191         * forwarded to another destination
192         */
193        Exchange copy();
194    
195        /**
196         * Copies the data into this exchange from the given exchange
197         * 
198         * @param source is the source from which headers and messages will be copied
199         */
200        void copyFrom(Exchange source);
201    
202        /**
203         * Returns the unit of work that this exchange belongs to; which may map to
204         * zero, one or more physical transactions
205         */
206        UnitOfWork getUnitOfWork();
207    
208        /**
209         * Sets the unit of work that this exchange belongs to; which may map to
210         * zero, one or more physical transactions
211         */
212        void setUnitOfWork(UnitOfWork unitOfWork);
213    
214        /**
215         * Returns the exchange id
216         *
217         * @return the unique id of the exchange
218         */
219        String getExchangeId();
220    
221        /**
222         * Set the exchange id
223         *
224         * @param id
225         */
226        void setExchangeId(String id);
227    
228    }