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