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 }