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