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 }