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://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">FAQ entry</a> 041 * before using. 042 * 043 * @version $Revision: 750400 $ 044 */ 045 public interface ProducerTemplate 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 Exchange send(Exchange 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 Exchange 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 a specified property and property 085 * value 086 * 087 * @param body the payload to send 088 * @param property the property name 089 * @param propertyValue the property value 090 * @return the result (see class javadoc) 091 */ 092 Object sendBodyAndProperty(Object body, String property, Object propertyValue); 093 094 /** 095 * Sends the body to the default endpoint with the specified headers and 096 * header values 097 * 098 * @param body the payload to send 099 * @param headers the headers 100 * @return the result (see class javadoc) 101 */ 102 Object sendBodyAndHeaders(Object body, Map<String, Object> headers); 103 104 // Allow sending to arbitrary endpoints 105 // ----------------------------------------------------------------------- 106 107 /** 108 * Sends the exchange to the given endpoint 109 * 110 * @param endpointUri the endpoint URI to send the exchange to 111 * @param exchange the exchange to send 112 * @return the returned exchange 113 */ 114 Exchange send(String endpointUri, Exchange exchange); 115 116 /** 117 * Sends an exchange to an endpoint using a supplied processor 118 * 119 * @param endpointUri the endpoint URI to send the exchange to 120 * @param processor the transformer used to populate the new exchange 121 * {@link Processor} to populate the exchange 122 * @return the returned exchange 123 */ 124 Exchange send(String endpointUri, Processor processor); 125 126 /** 127 * Sends an exchange to an endpoint using a supplied processor 128 * 129 * @param endpointUri the endpoint URI to send the exchange to 130 * @param pattern the message {@link ExchangePattern} such as 131 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 132 * @param processor the transformer used to populate the new exchange 133 * {@link Processor} to populate the exchange 134 * @return the returned exchange 135 */ 136 Exchange send(String endpointUri, ExchangePattern pattern, Processor processor); 137 138 /** 139 * Sends an exchange to an endpoint using a supplied processor 140 * 141 * @param endpointUri the endpoint URI to send the exchange to 142 * @param processor the transformer used to populate the new exchange 143 * {@link Processor} to populate the exchange. 144 * @param callback the callback will be called when the exchange is completed. 145 * @return the returned exchange 146 */ 147 Exchange send(String endpointUri, Processor processor, AsyncCallback callback); 148 149 /** 150 * Sends the exchange to the given endpoint 151 * 152 * @param endpoint the endpoint to send the exchange to 153 * @param exchange the exchange to send 154 * @return the returned exchange 155 */ 156 Exchange send(Endpoint endpoint, Exchange exchange); 157 158 /** 159 * Sends an exchange to an endpoint using a supplied processor 160 * 161 * @param endpoint the endpoint to send the exchange to 162 * @param processor the transformer used to populate the new exchange 163 * {@link Processor} to populate the exchange 164 * @return the returned exchange 165 */ 166 Exchange send(Endpoint endpoint, Processor processor); 167 168 /** 169 * Sends an exchange to an endpoint using a supplied processor 170 * 171 * @param endpoint the endpoint to send the exchange to 172 * @param pattern the message {@link ExchangePattern} such as 173 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 174 * @param processor the transformer used to populate the new exchange 175 * {@link Processor} to populate the exchange 176 * @return the returned exchange 177 */ 178 Exchange send(Endpoint endpoint, ExchangePattern pattern, Processor processor); 179 180 /** 181 * Sends an exchange to an endpoint using a supplied processor 182 * 183 * @param endpoint the endpoint to send the exchange to 184 * @param processor the transformer used to populate the new exchange 185 * {@link Processor} to populate the exchange. 186 * @param callback the callback will be called when the exchange is completed. 187 * @return the returned exchange 188 */ 189 Exchange send(Endpoint endpoint, Processor processor, AsyncCallback callback); 190 191 /** 192 * Send the body to an endpoint returning any result output body 193 * 194 * @param endpoint the endpoint to send the exchange to 195 * @param body the payload 196 * @return the result (see class javadoc) 197 */ 198 Object sendBody(Endpoint endpoint, Object body); 199 200 /** 201 * Send the body to an endpoint returning any result output body 202 * 203 * @param endpointUri the endpoint URI to send the exchange to 204 * @param body the payload 205 * @return the result (see class javadoc) 206 */ 207 Object sendBody(String endpointUri, Object body); 208 209 /** 210 * Send the body to an endpoint with the given {@link ExchangePattern} 211 * returning any result output body 212 * 213 * @param endpoint the endpoint to send the exchange to 214 * @param body the payload 215 * @param pattern the message {@link ExchangePattern} such as 216 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 217 * @return the result (see class javadoc) 218 */ 219 Object sendBody(Endpoint endpoint, ExchangePattern pattern, Object body); 220 221 /** 222 * Send the body to an endpoint returning any result output body 223 * 224 * @param endpointUri the endpoint URI to send the exchange to 225 * @param pattern the message {@link ExchangePattern} such as 226 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 227 * @param body the payload 228 * @return the result (see class javadoc) 229 */ 230 Object sendBody(String endpointUri, ExchangePattern pattern, Object body); 231 232 /** 233 * Sends the body to an endpoint with a specified header and header value 234 * 235 * @param endpointUri the endpoint URI to send to 236 * @param body the payload to send 237 * @param header the header name 238 * @param headerValue the header value 239 * @return the result (see class javadoc) 240 */ 241 Object sendBodyAndHeader(String endpointUri, Object body, String header, 242 Object headerValue); 243 244 /** 245 * Sends the body to an endpoint with a specified header and header value 246 * 247 * @param endpoint the Endpoint to send to 248 * @param body the payload to send 249 * @param header the header name 250 * @param headerValue the header value 251 * @return the result (see class javadoc) 252 */ 253 Object sendBodyAndHeader(Endpoint endpoint, Object body, String header, 254 Object headerValue); 255 256 /** 257 * Sends the body to an endpoint with a specified header and header value 258 * 259 * @param endpoint the Endpoint to send to 260 * @param pattern the message {@link ExchangePattern} such as 261 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 262 * @param body the payload to send 263 * @param header the header name 264 * @param headerValue the header value 265 * @return the result (see class javadoc) 266 */ 267 Object sendBodyAndHeader(Endpoint endpoint, ExchangePattern pattern, Object body, String header, 268 Object headerValue); 269 270 /** 271 * Sends the body to an endpoint with a specified header and header value 272 * 273 * @param endpoint the Endpoint URI to send to 274 * @param pattern the message {@link ExchangePattern} such as 275 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 276 * @param body the payload to send 277 * @param header the header name 278 * @param headerValue the header value 279 * @return the result (see class javadoc) 280 */ 281 Object sendBodyAndHeader(String endpoint, ExchangePattern pattern, Object body, String header, 282 Object headerValue); 283 284 /** 285 * Sends the body to an endpoint with a specified property and property value 286 * 287 * @param endpointUri the endpoint URI to send to 288 * @param body the payload to send 289 * @param property the property name 290 * @param propertyValue the property value 291 * @return the result (see class javadoc) 292 */ 293 Object sendBodyAndProperty(String endpointUri, Object body, String property, 294 Object propertyValue); 295 296 /** 297 * Sends the body to an endpoint with a specified property and property value 298 * 299 * @param endpoint the Endpoint to send to 300 * @param body the payload to send 301 * @param property the property name 302 * @param propertyValue the property value 303 * @return the result (see class javadoc) 304 */ 305 Object sendBodyAndProperty(Endpoint endpoint, Object body, String property, 306 Object propertyValue); 307 308 /** 309 * Sends the body to an endpoint with a specified property and property value 310 * 311 * @param endpoint the Endpoint to send to 312 * @param pattern the message {@link ExchangePattern} such as 313 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 314 * @param body the payload to send 315 * @param property the property name 316 * @param propertyValue the property value 317 * @return the result (see class javadoc) 318 */ 319 Object sendBodyAndProperty(Endpoint endpoint, ExchangePattern pattern, Object body, String property, 320 Object propertyValue); 321 322 /** 323 * Sends the body to an endpoint with a specified property and property value 324 * 325 * @param endpoint the Endpoint URI to send to 326 * @param pattern the message {@link ExchangePattern} such as 327 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 328 * @param body the payload to send 329 * @param property the property name 330 * @param propertyValue the property value 331 * @return the result (see class javadoc) 332 */ 333 Object sendBodyAndProperty(String endpoint, ExchangePattern pattern, Object body, String property, 334 Object propertyValue); 335 336 /** 337 * Sends the body to an endpoint with the specified headers and header 338 * values 339 * 340 * @param endpointUri the endpoint URI to send to 341 * @param body the payload to send 342 * @param headers headers 343 * @return the result (see class javadoc) 344 */ 345 Object sendBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers); 346 347 /** 348 * Sends the body to an endpoint with the specified headers and header 349 * values 350 * 351 * @param endpoint the endpoint URI to send to 352 * @param body the payload to send 353 * @param headers headers 354 * @return the result (see class javadoc) 355 */ 356 Object sendBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers); 357 358 /** 359 * Sends the body to an endpoint with the specified headers and header 360 * values 361 * 362 * @param endpointUri the endpoint URI to send to 363 * @param pattern the message {@link ExchangePattern} such as 364 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 365 * @param body the payload to send 366 * @param headers headers 367 * @return the result (see class javadoc) 368 */ 369 Object sendBodyAndHeaders(String endpointUri, ExchangePattern pattern, Object body, 370 Map<String, Object> headers); 371 372 /** 373 * Sends the body to an endpoint with the specified headers and header 374 * values 375 * 376 * @param endpoint the endpoint URI to send to 377 * @param pattern the message {@link ExchangePattern} such as 378 * {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut} 379 * @param body the payload to send 380 * @param headers headers 381 * @return the result (see class javadoc) 382 */ 383 Object sendBodyAndHeaders(Endpoint endpoint, ExchangePattern pattern, Object body, 384 Map<String, Object> headers); 385 386 387 // Methods using an InOut ExchangePattern 388 // ----------------------------------------------------------------------- 389 390 /** 391 * Sends an exchange to an endpoint using a supplied processor 392 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 393 * 394 * @param endpoint the Endpoint to send to 395 * @param processor the processor which will populate the exchange before sending 396 * @return the result (see class javadoc) 397 */ 398 Exchange request(Endpoint endpoint, Processor processor); 399 400 /** 401 * Sends an exchange to an endpoint using a supplied processor 402 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 403 * 404 * @param endpointUri the endpoint URI to send to 405 * @param processor the processor which will populate the exchange before sending 406 * @return the result (see class javadoc) 407 */ 408 Exchange request(String endpointUri, Processor processor); 409 410 /** 411 * Sends the body to the default endpoint and returns the result content 412 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 413 * 414 * @param body the payload to send 415 * @return the result (see class javadoc) 416 */ 417 Object requestBody(Object body); 418 419 /** 420 * Send the body to an endpoint returning any result output body. 421 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 422 * 423 * @param endpoint the Endpoint to send to 424 * @param body the payload 425 * @return the result (see class javadoc) 426 */ 427 Object requestBody(Endpoint endpoint, Object body); 428 429 /** 430 * Send the body to an endpoint returning any result output body. 431 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 432 * 433 * @param endpointUri the endpoint URI to send to 434 * @param body the payload 435 * @return the result (see class javadoc) 436 */ 437 Object requestBody(String endpointUri, Object body); 438 439 /** 440 * Send the body to an endpoint returning any result output body. 441 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 442 * 443 * @param endpoint the Endpoint to send to 444 * @param body the payload 445 * @param header the header name 446 * @param headerValue the header value 447 * @return the result (see class javadoc) 448 */ 449 Object requestBodyAndHeader(Endpoint endpoint, Object body, String header, Object headerValue); 450 451 /** 452 * Send the body to an endpoint returning any result output body. 453 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 454 * 455 * @param endpointUri the endpoint URI to send to 456 * @param body the payload 457 * @param header the header name 458 * @param headerValue the header value 459 * @return the result (see class javadoc) 460 */ 461 Object requestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue); 462 463 /** 464 * Sends the body to an endpoint with the specified headers and header 465 * values. 466 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 467 * 468 * @param endpointUri the endpoint URI to send to 469 * @param body the payload to send 470 * @param headers headers 471 * @return the result (see class javadoc) 472 */ 473 Object requestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers); 474 475 /** 476 * Sends the body to an endpoint with the specified headers and header 477 * values. 478 * Uses an {@link ExchangePattern#InOut} message exchange pattern. 479 * 480 * @param endpoint the endpoint URI to send to 481 * @param body the payload to send 482 * @param headers headers 483 * @return the result (see class javadoc) 484 */ 485 Object requestBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers); 486 }