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