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