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 }