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 }