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: 752465 $
030 */
031 public interface Exchange {
032
033 String BEAN_METHOD_NAME = "CamelBeanMethodName";
034 String BEAN_HOLDER = "CamelBeanHolder";
035 String BEAN_MULTI_PARAMETER_ARRAY = "CamelBeanMultiParameterArray";
036
037 String AGGREGATED_SIZE = "CamelAggregatedSize";
038
039 String CHARSET_NAME = "CamelCharsetName";
040
041 String DATASET_INDEX = "CamelDataSetIndex";
042
043 String EXCEPTION_CAUGHT = "CamelExceptionCaught";
044 String EXCEPTION_HANDLED = "CamelExceptionHandled";
045 String FAILURE_HANDLED = "CamelFailureHandled";
046
047 String FILE_BATCH_INDEX = "CamelFileBatchIndex";
048 String FILE_BATCH_SIZE = "CamelFileBatchSize";
049 String FILE_LOCAL_WORK_PATH = "CamelFileLocalWorkPath";
050 String FILE_NAME = "CamelFileName";
051 String FILE_NAME_ONLY = "CamelFileNameOnly";
052 String FILE_NAME_PRODUCED = "CamelFileNameProduced";
053
054 String LOOP_INDEX = "CamelLoopIndex";
055 String LOOP_SIZE = "CamelLoopSize";
056
057 String PROCESSED_SYNC = "CamelProcessedSync";
058
059 String REDELIVERED = "CamelRedelivered";
060 String REDELIVERY_COUNTER = "CamelRedeliveryCounter";
061
062 String SPLIT_INDEX = "CamelSplitIndex";
063 String SPLIT_SIZE = "CamelSplitSize";
064
065 String TIMER_NAME = "CamelTimerName";
066 String TIMER_FIRED_TIME = "CamelTimerFiredTime";
067 String TIMER_PERIOD = "CamelTimerPeriod";
068 String TIMER_TIME = "CamelTimerTime";
069
070 String TRANSACTED = "CamelTransacted";
071
072 /**
073 * Returns the {@link ExchangePattern} (MEP) of this exchange.
074 *
075 * @return the message exchange pattern of this exchange
076 */
077 ExchangePattern getPattern();
078
079 /**
080 * Allows the {@link ExchangePattern} (MEP) of this exchange to be customized.
081 *
082 * This typically won't be required as an exchange can be created with a specific MEP
083 * by calling {@link Endpoint#createExchange(ExchangePattern)} but it is here just in case
084 * it is needed.
085 *
086 * @param pattern the pattern
087 */
088 void setPattern(ExchangePattern pattern);
089
090 /**
091 * Returns a property associated with this exchange by name
092 *
093 * @param name the name of the property
094 * @return the value of the given header or null if there is no property for
095 * the given name
096 */
097 Object getProperty(String name);
098
099 /**
100 * Returns a property associated with this exchange by name and specifying
101 * the type required
102 *
103 * @param name the name of the property
104 * @param type the type of the property
105 * @return the value of the given header or null if there is no property for
106 * the given name or null if it cannot be converted to the given
107 * type
108 */
109 <T> T getProperty(String name, Class<T> type);
110
111 /**
112 * Sets a property on the exchange
113 *
114 * @param name of the property
115 * @param value to associate with the name
116 */
117 void setProperty(String name, Object value);
118
119 /**
120 * Removes the given property on the exchange
121 *
122 * @param name of the property
123 * @return the old value of the property
124 */
125 Object removeProperty(String name);
126
127 /**
128 * Returns all of the properties associated with the exchange
129 *
130 * @return all the headers in a Map
131 */
132 Map<String, Object> getProperties();
133
134 /**
135 * Returns the inbound request message
136 *
137 * @return the message
138 */
139 Message getIn();
140
141 /**
142 * Sets the inbound message instance
143 *
144 * @param in the inbound message
145 */
146 void setIn(Message in);
147
148 /**
149 * Returns the outbound message, lazily creating one if one has not already
150 * been associated with this exchange. If you want to inspect this property
151 * but not force lazy creation then invoke the {@link #getOut(boolean)}
152 * method passing in <tt>false</tt>
153 *
154 * @return the response
155 */
156 Message getOut();
157
158 /**
159 * Returns the outbound message; optionally lazily creating one if one has
160 * not been associated with this exchange
161 *
162 * @param lazyCreate <tt>true</tt> will lazy create the out message
163 * @return the response
164 */
165 Message getOut(boolean lazyCreate);
166
167 /**
168 * Sets the outbound message
169 *
170 * @param out the outbound message
171 */
172 void setOut(Message out);
173
174 /**
175 * Returns the fault message
176 *
177 * @return the fault
178 */
179 Message getFault();
180
181 /**
182 * Returns the fault message; optionally lazily creating one if one has
183 * not been associated with this exchange
184 *
185 * @param lazyCreate <tt>true</tt> will lazy create the fault message
186 * @return the fault
187 */
188 Message getFault(boolean lazyCreate);
189
190 /**
191 * Returns the exception associated with this exchange
192 *
193 * @return the exception (or null if no faults)
194 */
195 Exception getException();
196
197 /**
198 * Sets the exception associated with this exchange
199 *
200 * @param e the caused exception
201 */
202 void setException(Exception e);
203
204 /**
205 * Returns true if this exchange failed due to either an exception or fault
206 *
207 * @return true if this exchange failed due to either an exception or fault
208 * @see Exchange#getException()
209 * @see Exchange#getFault()
210 */
211 boolean isFailed();
212
213 /**
214 * Returns true if this exchange is transacted
215 */
216 boolean isTransacted();
217
218 /**
219 * Returns the container so that a processor can resolve endpoints from URIs
220 *
221 * @return the container which owns this exchange
222 */
223 CamelContext getContext();
224
225 /**
226 * Creates a new exchange instance with empty messages, headers and properties
227 */
228 Exchange newInstance();
229
230 /**
231 * Creates a copy of the current message exchange so that it can be
232 * forwarded to another destination
233 */
234 Exchange copy();
235
236 /**
237 * Copies the data into this exchange from the given exchange
238 *
239 * @param source is the source from which headers and messages will be copied
240 */
241 void copyFrom(Exchange source);
242
243
244 /**
245 * Returns the endpoint which originated this message exchange if a consumer on an endpoint created the message exchange
246 * otherwise this property will be null
247 */
248 Endpoint getFromEndpoint();
249
250 /**
251 * Sets the endpoint which originated this message exchange. This method
252 * should typically only be called by {@link org.apache.camel.Endpoint} implementations
253 *
254 * @param fromEndpoint the endpoint which is originating this message exchange
255 */
256 void setFromEndpoint(Endpoint fromEndpoint);
257
258 /**
259 * Returns the unit of work that this exchange belongs to; which may map to
260 * zero, one or more physical transactions
261 */
262 UnitOfWork getUnitOfWork();
263
264 /**
265 * Sets the unit of work that this exchange belongs to; which may map to
266 * zero, one or more physical transactions
267 */
268 void setUnitOfWork(UnitOfWork unitOfWork);
269
270 /**
271 * Returns the exchange id (unique)
272 */
273 String getExchangeId();
274
275 /**
276 * Set the exchange id
277 */
278 void setExchangeId(String id);
279
280 }