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 /** 022 * Template (named like Spring's TransactionTemplate & JmsTemplate 023 * et al) for working with Camel and sending {@link Message} instances in an 024 * {@link Exchange} to an {@link Endpoint}. 025 * <p/> 026 * <b>All</b> methods throws {@link RuntimeCamelException} if processing of 027 * the {@link Exchange} failed and an Exception occured. The <tt>getCause</tt> 028 * method on {@link RuntimeCamelException} returns the wrapper original caused 029 * exception. 030 * <p/> 031 * All the send<b>Body</b> methods will return the content according to this strategy 032 * <ul> 033 * <li>throws {@link RuntimeCamelException} as stated above</li> 034 * <li>The <tt>fault.body</tt> if there is a fault message set and its not <tt>null</tt></li> 035 * <li>Either <tt>IN</tt> or <tt>OUT</tt> body according to the message exchange pattern. If the pattern is 036 * Out capable then the <tt>OUT</tt> body is returned, otherwise <tt>IN</tt>. 037 * </ul> 038 * <p/> 039 * <b>Important note on usage:</b> See this 040 * <a href="http://activemq.apache.org/camel/why-does-camel-use-too-many-threads-with-producertemplate.html">FAQ entry</a> 041 * before using. 042 * 043 * @version $Revision: 64758 $ 044 */ 045 public interface ProducerTemplate<E extends Exchange> extends Service { 046 047 /** 048 * Sends the exchange to the default endpoint 049 * 050 * @param exchange the exchange to send 051 * @return the returned exchange 052 */ 053 E send(E exchange); 054 055 /** 056 * Sends an exchange to the default endpoint using a supplied processor 057 * 058 * @param processor the transformer used to populate the new exchange 059 * {@link Processor} to populate the exchange 060 * @return the returned exchange 061 */ 062 E send(Processor processor); 063 064 /** 065 * Sends the body to the default endpoint and returns the result content 066 * 067 * @param body the payload to send 068 * @return the result (see class javadoc) 069 */ 070 Object sendBody(Object body); 071 072 /** 073 * Sends the body to the default endpoint with a specified header and header 074 * value 075 * 076 * @param body the payload to send 077 * @param header the header name 078 * @param headerValue the header value 079 * @return the result (see class javadoc) 080 */ 081 Object sendBodyAndHeader(Object body, String header, Object headerValue); 082 083 /** 084 * Sends the body to the default endpoint with the specified headers and 085 * header values 086 * 087 * @param body the payload to send 088 * @param headers the headers 089 * @return the result (see class javadoc) 090 */ 091 Object sendBodyAndHeaders(Object body, Map<String, Object> headers); 092 093 // Allow sending to arbitrary endpoints 094 // ----------------------------------------------------------------------- 095 096 /** 097 * Sends the exchange to the given endpoint 098 * 099 * @param endpointUri the endpoint URI to send the exchange to 100 * @param exchange the exchange to send 101 * @return the returned exchange 102 */ 103 E send(String endpointUri, E exchange); 104 105 /** 106 * Sends an exchange to an endpoint using a supplied processor 107 * 108 * @param endpointUri the endpoint URI to send the exchange to 109 * @param processor the transformer used to populate the new exchange 110 * {@link Processor} to populate the exchange 111 * @return the returned exchange 112 */ 113 E send(String endpointUri, Processor processor); 114 115 /** 116 * Sends an exchange to an endpoint using a supplied processor 117 * 118 * @param endpointUri the endpoint URI to send the exchange to 119 * @param pattern the message {@link ExchangePattern} such as 120 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 121 * @param processor the transformer used to populate the new exchange 122 * {@link Processor} to populate the exchange 123 * @return the returned exchange 124 */ 125 E send(String endpointUri, ExchangePattern pattern, Processor processor); 126 127 /** 128 * Sends an exchange to an endpoint using a supplied processor 129 * 130 * @param endpointUri the endpoint URI to send the exchange to 131 * @param processor the transformer used to populate the new exchange 132 * {@link Processor} to populate the exchange. 133 * @param callback the callback will be called when the exchange is completed. 134 * @return the returned exchange 135 */ 136 E send(String endpointUri, Processor processor, AsyncCallback callback); 137 138 /** 139 * Sends the exchange to the given endpoint 140 * 141 * @param endpoint the endpoint to send the exchange to 142 * @param exchange the exchange to send 143 * @return the returned exchange 144 */ 145 E send(Endpoint<E> endpoint, E exchange); 146 147 /** 148 * Sends an exchange to an endpoint using a supplied processor 149 * 150 * @param endpoint the endpoint to send the exchange to 151 * @param processor the transformer used to populate the new exchange 152 * {@link Processor} to populate the exchange 153 * @return the returned exchange 154 */ 155 E send(Endpoint<E> endpoint, Processor processor); 156 157 /** 158 * Sends an exchange to an endpoint using a supplied processor 159 * 160 * @param endpoint the endpoint to send the exchange to 161 * @param pattern the message {@link ExchangePattern} such as 162 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 163 * @param processor the transformer used to populate the new exchange 164 * {@link Processor} to populate the exchange 165 * @return the returned exchange 166 */ 167 E send(Endpoint<E> endpoint, ExchangePattern pattern, Processor processor); 168 169 /** 170 * Sends an exchange to an endpoint using a supplied processor 171 * 172 * @param endpoint the endpoint to send the exchange to 173 * @param processor the transformer used to populate the new exchange 174 * {@link Processor} to populate the exchange. 175 * @param callback the callback will be called when the exchange is completed. 176 * @return the returned exchange 177 */ 178 E send(Endpoint<E> endpoint, Processor processor, AsyncCallback callback); 179 180 /** 181 * Send the body to an endpoint returning any result output body 182 * 183 * @param endpoint the endpoint to send the exchange to 184 * @param body the payload 185 * @return the result (see class javadoc) 186 */ 187 Object sendBody(Endpoint<E> endpoint, Object body); 188 189 /** 190 * Send the body to an endpoint returning any result output body 191 * 192 * @param endpointUri the endpoint URI to send the exchange to 193 * @param body the payload 194 * @return the result (see class javadoc) 195 */ 196 Object sendBody(String endpointUri, Object body); 197 198 /** 199 * Send the body to an endpoint with the given {@link ExchangePattern} 200 * returning any result output body 201 * 202 * @param endpoint the endpoint to send the exchange to 203 * @param body the payload 204 * @param pattern the message {@link ExchangePattern} such as 205 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 206 * @return the result (see class javadoc) 207 */ 208 Object sendBody(Endpoint<E> endpoint, ExchangePattern pattern, Object body); 209 210 /** 211 * Send the body to an endpoint returning any result output body 212 * 213 * @param endpointUri the endpoint URI to send the exchange to 214 * @param pattern the message {@link ExchangePattern} such as 215 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 216 * @param body the payload 217 * @return the result (see class javadoc) 218 */ 219 Object sendBody(String endpointUri, ExchangePattern pattern, Object body); 220 221 /** 222 * Sends the body to an endpoint with a specified header and header value 223 * 224 * @param endpointUri the endpoint URI to send to 225 * @param body the payload to send 226 * @param header the header name 227 * @param headerValue the header value 228 * @return the result (see class javadoc) 229 */ 230 Object sendBodyAndHeader(String endpointUri, Object body, String header, 231 Object headerValue); 232 233 /** 234 * Sends the body to an endpoint with a specified header and header value 235 * 236 * @param endpoint the Endpoint to send to 237 * @param body the payload to send 238 * @param header the header name 239 * @param headerValue the header value 240 * @return the result (see class javadoc) 241 */ 242 Object sendBodyAndHeader(Endpoint<E> endpoint, Object body, String header, 243 Object headerValue); 244 245 /** 246 * Sends the body to an endpoint with a specified header and header value 247 * 248 * @param endpoint the Endpoint to send to 249 * @param pattern the message {@link ExchangePattern} such as 250 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 251 * @param body the payload to send 252 * @param header the header name 253 * @param headerValue the header value 254 * @return the result (see class javadoc) 255 */ 256 Object sendBodyAndHeader(Endpoint<E> endpoint, ExchangePattern pattern, Object body, String header, 257 Object headerValue); 258 259 /** 260 * Sends the body to an endpoint with a specified header and header value 261 * 262 * @param endpoint the Endpoint URI to send to 263 * @param pattern the message {@link ExchangePattern} such as 264 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 265 * @param body the payload to send 266 * @param header the header name 267 * @param headerValue the header value 268 * @return the result (see class javadoc) 269 */ 270 Object sendBodyAndHeader(String endpoint, ExchangePattern pattern, Object body, String header, 271 Object headerValue); 272 273 /** 274 * Sends the body to an endpoint with the specified headers and header 275 * values 276 * 277 * @param endpointUri the endpoint URI to send to 278 * @param body the payload to send 279 * @param headers headers 280 * @return the result (see class javadoc) 281 */ 282 Object sendBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers); 283 284 /** 285 * Sends the body to an endpoint with the specified headers and header 286 * values 287 * 288 * @param endpoint the endpoint URI to send to 289 * @param body the payload to send 290 * @param headers headers 291 * @return the result (see class javadoc) 292 */ 293 Object sendBodyAndHeaders(Endpoint<E> endpoint, Object body, Map<String, Object> headers); 294 295 /** 296 * Sends the body to an endpoint with the specified headers and header 297 * values 298 * 299 * @param endpointUri the endpoint URI to send to 300 * @param pattern the message {@link ExchangePattern} such as 301 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 302 * @param body the payload to send 303 * @param headers headers 304 * @return the result (see class javadoc) 305 */ 306 Object sendBodyAndHeaders(String endpointUri, ExchangePattern pattern, Object body, 307 Map<String, Object> headers); 308 309 /** 310 * Sends the body to an endpoint with the specified headers and header 311 * values 312 * 313 * @param endpoint the endpoint URI to send to 314 * @param pattern the message {@link ExchangePattern} such as 315 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 316 * @param body the payload to send 317 * @param headers headers 318 * @return the result (see class javadoc) 319 */ 320 Object sendBodyAndHeaders(Endpoint<E> endpoint, ExchangePattern pattern, Object body, 321 Map<String, Object> headers); 322 323 324 // Methods using an InOut ExchangePattern 325 // ----------------------------------------------------------------------- 326 327 /** 328 * Sends an exchange to an endpoint using a supplied processor 329 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 330 * 331 * @param endpoint the Endpoint to send to 332 * @param processor the processor which will populate the exchange before sending 333 * @return the result (see class javadoc) 334 */ 335 E request(Endpoint<E> endpoint, Processor processor); 336 337 /** 338 * Sends an exchange to an endpoint using a supplied processor 339 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 340 * 341 * @param endpointUri the endpoint URI to send to 342 * @param processor the processor which will populate the exchange before sending 343 * @return the result (see class javadoc) 344 */ 345 Exchange request(String endpointUri, Processor processor); 346 347 /** 348 * Send the body to an endpoint returning any result output body. 349 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 350 * 351 * @param endpoint the Endpoint to send to 352 * @param body the payload 353 * @return the result (see class javadoc) 354 */ 355 Object requestBody(Endpoint<E> endpoint, Object body); 356 357 /** 358 * Send the body to an endpoint returning any result output body. 359 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 360 * 361 * @param endpointUri the endpoint URI to send to 362 * @param body the payload 363 * @return the result (see class javadoc) 364 */ 365 Object requestBody(String endpointUri, Object body); 366 367 /** 368 * Send the body to an endpoint returning any result output body. 369 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 370 * 371 * @param endpoint the Endpoint to send to 372 * @param body the payload 373 * @param header the header name 374 * @param headerValue the header value 375 * @return the result (see class javadoc) 376 */ 377 Object requestBodyAndHeader(Endpoint<E> endpoint, Object body, String header, Object headerValue); 378 379 /** 380 * Send the body to an endpoint returning any result output body. 381 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 382 * 383 * @param endpointUri the endpoint URI to send to 384 * @param body the payload 385 * @param header the header name 386 * @param headerValue the header value 387 * @return the result (see class javadoc) 388 */ 389 Object requestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue); 390 391 /** 392 * Sends the body to an endpoint with the specified headers and header 393 * values. 394 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 395 * 396 * @param endpointUri the endpoint URI to send to 397 * @param body the payload to send 398 * @param headers headers 399 * @return the result (see class javadoc) 400 */ 401 Object requestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers); 402 403 /** 404 * Sends the body to an endpoint with the specified headers and header 405 * values. 406 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 407 * 408 * @param endpoint the endpoint URI to send to 409 * @param body the payload to send 410 * @param headers headers 411 * @return the result (see class javadoc) 412 */ 413 Object requestBodyAndHeaders(Endpoint<E> endpoint, Object body, Map<String, Object> headers); 414 }