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