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    import java.util.concurrent.ExecutorService;
021    import java.util.concurrent.Future;
022    import java.util.concurrent.TimeUnit;
023    import java.util.concurrent.TimeoutException;
024    
025    import org.apache.camel.spi.Synchronization;
026    
027    /**
028     * Template for working with Camel and sending {@link Message} instances in an
029     * {@link Exchange} to an {@link Endpoint}.
030     * <br/>
031     * <p/><b>Important:</b> Read the javadoc of each method carefully to ensure the behavior of the method is understood.
032     * Some methods is for <tt>InOnly</tt>, others for <tt>InOut</tt> MEP. And some methods throws
033     * {@link org.apache.camel.CamelExecutionException} while others stores any thrown exception on the returned
034     * {@link Exchange}.
035     * <br/>
036     * <p/>The {@link ProducerTemplate} is <b>thread safe</b>.
037     * <br/>
038     * <p/>All the methods which sends a message may throw {@link FailedToCreateProducerException} in
039     * case the {@link Producer} could not be created. Or a {@link NoSuchEndpointException} if the endpoint could
040     * not be resolved. There may be other related exceptions being thrown which occurs <i>before</i> the {@link Producer}
041     * has started sending the message.
042     * <br/>
043     * <p/>All the sendBody or requestBody methods will return the content according to this strategy:
044     * <ul>
045     *   <li>throws {@link org.apache.camel.CamelExecutionException} if processing failed <i>during</i> routing
046     *       with the caused exception wrapped</li>
047     *   <li>The <tt>fault.body</tt> if there is a fault message set and its not <tt>null</tt></li>
048     *   <li>Either <tt>IN</tt> or <tt>OUT</tt> body according to the message exchange pattern. If the pattern is
049     *   Out capable then the <tt>OUT</tt> body is returned, otherwise <tt>IN</tt>.
050     * </ul>
051     * <br/>
052     * <p/>Before using the template it must be started.
053     * And when you are done using the template, make sure to {@link #stop()} the template.
054     * <br/>
055     * <p/><b>Important note on usage:</b> See this
056     * <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">FAQ entry</a>
057     * before using.
058     *
059     * @version 
060     */
061    public interface ProducerTemplate extends Service {
062    
063        /**
064         * Get the {@link CamelContext}
065         *
066         * @return camelContext the Camel context
067         */
068        CamelContext getCamelContext();
069    
070        // Configuration methods
071        // -----------------------------------------------------------------------
072    
073        /**
074         * Gets the maximum cache size used in the backing cache pools.
075         *
076         * @return the maximum cache size
077         */
078        int getMaximumCacheSize();
079    
080        /**
081         * Sets a custom maximum cache size to use in the backing cache pools.
082         *
083         * @param maximumCacheSize the custom maximum cache size
084         */
085        void setMaximumCacheSize(int maximumCacheSize);
086    
087        /**
088         * Gets an approximated size of the current cached resources in the backing cache pools.
089         *
090         * @return the size of current cached resources
091         */
092        int getCurrentCacheSize();
093        
094        /**
095         * Get the default endpoint to use if none is specified
096         * 
097         * @return the default endpoint instance
098         */
099        Endpoint getDefaultEndpoint();
100        
101        /**
102         * Sets the default endpoint to use if none is specified
103         * 
104         * @param defaultEndpoint the default endpoint instance
105         */
106        void setDefaultEndpoint(Endpoint defaultEndpoint);
107    
108        /**
109         * Sets the default endpoint uri to use if none is specified
110         * 
111         *  @param endpointUri the default endpoint uri
112         */
113        void setDefaultEndpointUri(String endpointUri);
114    
115        // Synchronous methods
116        // -----------------------------------------------------------------------
117    
118        /**
119         * Sends the exchange to the default endpoint
120         * <br/><br/>
121         * <b>Notice:</b> that if the processing of the exchange failed with an Exception
122         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
123         * {@link org.apache.camel.Exchange#getException()}.
124         *
125         * @param exchange the exchange to send
126         * @return the returned exchange
127         */
128        Exchange send(Exchange exchange);
129    
130        /**
131         * Sends an exchange to the default endpoint using a supplied processor
132         * <br/><br/>
133         * <b>Notice:</b> that if the processing of the exchange failed with an Exception
134         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
135         * {@link org.apache.camel.Exchange#getException()}.
136         *
137         * @param processor the transformer used to populate the new exchange
138         * {@link Processor} to populate the exchange
139         * @return the returned exchange
140         */
141        Exchange send(Processor processor);
142    
143        /**
144         * Sends the body to the default endpoint
145         * <br/><br/>
146         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
147         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
148         * the caused exception wrapped.
149         *
150         * @param body the payload to send
151         * @throws CamelExecutionException if the processing of the exchange failed
152         */
153        void sendBody(Object body) throws CamelExecutionException;
154    
155        /**
156         * Sends the body to the default endpoint with a specified header and header value
157         * <br/><br/>
158         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
159         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
160         * the caused exception wrapped.
161         *
162         * @param body the payload to send
163         * @param header the header name
164         * @param headerValue the header value
165         * @throws CamelExecutionException if the processing of the exchange failed
166         */
167        void sendBodyAndHeader(Object body, String header, Object headerValue) throws CamelExecutionException;
168    
169        /**
170         * Sends the body to the default endpoint with a specified property and property value
171         * <br/><br/>
172         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
173         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
174         * the caused exception wrapped.
175         *
176         * @param body          the payload to send
177         * @param property      the property name
178         * @param propertyValue the property value
179         * @throws CamelExecutionException if the processing of the exchange failed
180         */
181        void sendBodyAndProperty(Object body, String property, Object propertyValue) throws CamelExecutionException;
182        
183        /**
184         * Sends the body to the default endpoint with the specified headers and header values
185         * <br/><br/>
186         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
187         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
188         * the caused exception wrapped.
189         *
190         * @param body the payload to send
191         * @param headers      the headers
192         * @throws CamelExecutionException if the processing of the exchange failed
193         */
194        void sendBodyAndHeaders(Object body, Map<String, Object> headers) throws CamelExecutionException;
195    
196        // Allow sending to arbitrary endpoints
197        // -----------------------------------------------------------------------
198    
199        /**
200         * Sends the exchange to the given endpoint
201         * <br/><br/>
202         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
203         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
204         * {@link org.apache.camel.Exchange#getException()}.
205         *
206         * @param endpointUri the endpoint URI to send the exchange to
207         * @param exchange    the exchange to send
208         * @return the returned exchange
209         * @throws CamelExecutionException if the processing of the exchange failed
210         */
211        Exchange send(String endpointUri, Exchange exchange);
212    
213        /**
214         * Sends an exchange to an endpoint using a supplied processor
215         * <br/><br/>
216         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
217         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
218         * {@link org.apache.camel.Exchange#getException()}.
219         *
220         * @param endpointUri the endpoint URI to send the exchange to
221         * @param processor   the transformer used to populate the new exchange
222         * {@link Processor} to populate the exchange
223         * @return the returned exchange
224         * @throws CamelExecutionException if the processing of the exchange failed
225         */
226        Exchange send(String endpointUri, Processor processor);
227    
228        /**
229         * Sends an exchange to an endpoint using a supplied processor
230         * <br/><br/>
231         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
232         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
233         * {@link org.apache.camel.Exchange#getException()}.
234         *
235         * @param endpointUri the endpoint URI to send the exchange to
236         * @param pattern     the message {@link ExchangePattern} such as
237         *                    {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
238         * @param processor   the transformer used to populate the new exchange
239         * {@link Processor} to populate the exchange
240         * @return the returned exchange
241         */
242        Exchange send(String endpointUri, ExchangePattern pattern, Processor processor);
243    
244        /**
245         * Sends the exchange to the given endpoint
246         * <br/><br/>
247         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
248         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
249         * {@link org.apache.camel.Exchange#getException()}.
250         *
251         * @param endpoint the endpoint to send the exchange to
252         * @param exchange the exchange to send
253         * @return the returned exchange
254         */
255        Exchange send(Endpoint endpoint, Exchange exchange);
256    
257        /**
258         * Sends an exchange to an endpoint using a supplied processor
259         * <br/><br/>
260         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
261         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
262         * {@link org.apache.camel.Exchange#getException()}.
263         *
264         * @param endpoint  the endpoint to send the exchange to
265         * @param processor the transformer used to populate the new exchange
266         * {@link Processor} to populate the exchange
267         * @return the returned exchange
268         */
269        Exchange send(Endpoint endpoint, Processor processor);
270    
271        /**
272         * Sends an exchange to an endpoint using a supplied processor
273         * <br/><br/>
274         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
275         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
276         * {@link org.apache.camel.Exchange#getException()}.
277         *
278         * @param endpoint  the endpoint to send the exchange to
279         * @param pattern   the message {@link ExchangePattern} such as
280         *                  {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
281         * @param processor the transformer used to populate the new exchange
282         * {@link Processor} to populate the exchange
283         * @return the returned exchange
284         */
285        Exchange send(Endpoint endpoint, ExchangePattern pattern, Processor processor);
286    
287        /**
288         * Send the body to an endpoint
289         * <br/><br/>
290         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
291         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
292         * the caused exception wrapped.
293         *
294         * @param endpoint   the endpoint to send the exchange to
295         * @param body       the payload
296         * @throws CamelExecutionException if the processing of the exchange failed
297         */
298        void sendBody(Endpoint endpoint, Object body) throws CamelExecutionException;
299    
300        /**
301         * Send the body to an endpoint
302         * <br/><br/>
303         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
304         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
305         * the caused exception wrapped.
306         *
307         * @param endpointUri   the endpoint URI to send the exchange to
308         * @param body          the payload
309         * @throws CamelExecutionException if the processing of the exchange failed
310         */
311        void sendBody(String endpointUri, Object body) throws CamelExecutionException;
312    
313        /**
314         * Send the body to an endpoint with the given {@link ExchangePattern}
315         * returning any result output body
316         * <br/><br/>
317         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
318         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
319         * the caused exception wrapped.
320         *
321         * @param endpoint      the endpoint to send the exchange to
322         * @param body          the payload
323         * @param pattern       the message {@link ExchangePattern} such as
324         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
325         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
326         * @throws CamelExecutionException if the processing of the exchange failed
327         */
328        Object sendBody(Endpoint endpoint, ExchangePattern pattern, Object body) throws CamelExecutionException;
329    
330        /**
331         * Send the body to an endpoint returning any result output body
332         * <br/><br/>
333         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
334         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
335         * the caused exception wrapped.
336         *
337         * @param endpointUri   the endpoint URI to send the exchange to
338         * @param pattern       the message {@link ExchangePattern} such as
339         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
340         * @param body          the payload
341         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
342         * @throws CamelExecutionException if the processing of the exchange failed
343         */
344        Object sendBody(String endpointUri, ExchangePattern pattern, Object body) throws CamelExecutionException;
345    
346        /**
347         * Sends the body to an endpoint with a specified header and header value
348         * <br/><br/>
349         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
350         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
351         * the caused exception wrapped.
352         *
353         * @param endpointUri the endpoint URI to send to
354         * @param body the payload to send
355         * @param header the header name
356         * @param headerValue the header value
357         * @throws CamelExecutionException if the processing of the exchange failed
358         */
359        void sendBodyAndHeader(String endpointUri, Object body, String header, Object headerValue) throws CamelExecutionException;
360    
361        /**
362         * Sends the body to an endpoint with a specified header and header value
363         * <br/><br/>
364         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
365         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
366         * the caused exception wrapped.
367         *
368         * @param endpoint the Endpoint to send to
369         * @param body the payload to send
370         * @param header the header name
371         * @param headerValue the header value
372         * @throws CamelExecutionException if the processing of the exchange failed
373         */
374        void sendBodyAndHeader(Endpoint endpoint, Object body, String header, Object headerValue) throws CamelExecutionException;
375    
376        /**
377         * Sends the body to an endpoint with a specified header and header value
378         * <br/><br/>
379         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
380         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
381         * the caused exception wrapped.
382         *
383         * @param endpoint the Endpoint to send to
384         * @param pattern the message {@link ExchangePattern} such as
385         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
386         * @param body the payload to send
387         * @param header the header name
388         * @param headerValue the header value
389         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
390         * @throws CamelExecutionException if the processing of the exchange failed
391         */
392        Object sendBodyAndHeader(Endpoint endpoint, ExchangePattern pattern, Object body,
393                                 String header, Object headerValue) throws CamelExecutionException;
394    
395        /**
396         * Sends the body to an endpoint with a specified header and header value
397         * <br/><br/>
398         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
399         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
400         * the caused exception wrapped.
401         *
402         * @param endpoint the Endpoint URI to send to
403         * @param pattern the message {@link ExchangePattern} such as
404         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
405         * @param body the payload to send
406         * @param header the header name
407         * @param headerValue the header value
408         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
409         * @throws CamelExecutionException if the processing of the exchange failed
410         */
411        Object sendBodyAndHeader(String endpoint, ExchangePattern pattern, Object body,
412                                 String header, Object headerValue) throws CamelExecutionException;
413    
414        /**
415         * Sends the body to an endpoint with a specified property and property value
416         * <br/><br/>
417         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
418         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
419         * the caused exception wrapped.
420         *
421         * @param endpointUri the endpoint URI to send to
422         * @param body the payload to send
423         * @param property the property name
424         * @param propertyValue the property value
425         * @throws CamelExecutionException if the processing of the exchange failed
426         */
427        void sendBodyAndProperty(String endpointUri, Object body, String property, Object propertyValue) throws CamelExecutionException;
428    
429        /**
430         * Sends the body to an endpoint with a specified property and property value
431         * <br/><br/>
432         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
433         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
434         * the caused exception wrapped.
435         *
436         * @param endpoint the Endpoint to send to
437         * @param body the payload to send
438         * @param property the property name
439         * @param propertyValue the property value
440         * @throws CamelExecutionException if the processing of the exchange failed
441         */
442        void sendBodyAndProperty(Endpoint endpoint, Object body, String property, Object propertyValue) throws CamelExecutionException;
443    
444        /**
445         * Sends the body to an endpoint with a specified property and property value
446         * <br/><br/>
447         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
448         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
449         * the caused exception wrapped.
450         *
451         * @param endpoint the Endpoint to send to
452         * @param pattern the message {@link ExchangePattern} such as
453         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
454         * @param body the payload to send
455         * @param property the property name
456         * @param propertyValue the property value
457         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
458         * @throws CamelExecutionException if the processing of the exchange failed
459         */
460        Object sendBodyAndProperty(Endpoint endpoint, ExchangePattern pattern, Object body,
461                                   String property, Object propertyValue) throws CamelExecutionException;
462    
463        /**
464         * Sends the body to an endpoint with a specified property and property value
465         * <br/><br/>
466         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
467         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
468         * the caused exception wrapped.
469         *
470         * @param endpoint the Endpoint URI to send to
471         * @param pattern the message {@link ExchangePattern} such as
472         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
473         * @param body the payload to send
474         * @param property the property name
475         * @param propertyValue the property value
476         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
477         * @throws CamelExecutionException if the processing of the exchange failed
478         */
479        Object sendBodyAndProperty(String endpoint, ExchangePattern pattern, Object body,
480                                   String property, Object propertyValue) throws CamelExecutionException;
481    
482        /**
483         * Sends the body to an endpoint with the specified headers and header values
484         * <br/><br/>
485         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
486         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
487         * the caused exception wrapped.
488         *
489         * @param endpointUri the endpoint URI to send to
490         * @param body the payload to send
491         * @param headers headers
492         * @throws CamelExecutionException if the processing of the exchange failed
493         */
494        void sendBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers) throws CamelExecutionException;
495    
496        /**
497         * Sends the body to an endpoint with the specified headers and header values
498         * <br/><br/>
499         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
500         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
501         * the caused exception wrapped.
502         *
503         * @param endpoint the endpoint URI to send to
504         * @param body the payload to send
505         * @param headers headers
506         * @throws CamelExecutionException if the processing of the exchange failed
507         */
508        void sendBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers) throws CamelExecutionException;
509    
510        /**
511         * Sends the body to an endpoint with the specified headers and header values
512         * <br/><br/>
513         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
514         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
515         * the caused exception wrapped.
516         *
517         * @param endpointUri the endpoint URI to send to
518         * @param pattern the message {@link ExchangePattern} such as
519         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
520         * @param body the payload to send
521         * @param headers headers
522         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
523         * @throws CamelExecutionException if the processing of the exchange failed
524         */
525        Object sendBodyAndHeaders(String endpointUri, ExchangePattern pattern, Object body,
526                                  Map<String, Object> headers) throws CamelExecutionException;
527    
528        /**
529         * Sends the body to an endpoint with the specified headers and header values
530         * <br/><br/>
531         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
532         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
533         * the caused exception wrapped.
534         *
535         * @param endpoint the endpoint URI to send to
536         * @param pattern the message {@link ExchangePattern} such as
537         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
538         * @param body the payload to send
539         * @param headers headers
540         * @return the result if {@link ExchangePattern} is OUT capable, otherwise <tt>null</tt>
541         * @throws CamelExecutionException if the processing of the exchange failed
542         */
543        Object sendBodyAndHeaders(Endpoint endpoint, ExchangePattern pattern, Object body,
544                                  Map<String, Object> headers) throws CamelExecutionException;
545    
546    
547        // Methods using an InOut ExchangePattern
548        // -----------------------------------------------------------------------
549    
550        /**
551         * Sends an exchange to an endpoint using a supplied processor
552         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
553         * <br/><br/>
554         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
555         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
556         * {@link org.apache.camel.Exchange#getException()}.
557         *
558         * @param endpoint  the Endpoint to send to
559         * @param processor the processor which will populate the exchange before sending
560         * @return the result (see class javadoc)
561         */
562        Exchange request(Endpoint endpoint, Processor processor);
563    
564        /**
565         * Sends an exchange to an endpoint using a supplied processor
566         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
567         * <br/><br/>
568         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
569         * it is <b>not</b> thrown from this method, but you can access it from the returned exchange using
570         * {@link org.apache.camel.Exchange#getException()}.
571         *
572         * @param endpointUri the endpoint URI to send to
573         * @param processor the processor which will populate the exchange before sending
574         * @return the result (see class javadoc)
575         */
576        Exchange request(String endpointUri, Processor processor);
577    
578        /**
579         * Sends the body to the default endpoint and returns the result content
580         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
581         * <br/><br/>
582         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
583         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
584         * the caused exception wrapped.
585         *
586         * @param body the payload to send
587         * @return the result (see class javadoc)
588         * @throws CamelExecutionException if the processing of the exchange failed
589         */
590        Object requestBody(Object body) throws CamelExecutionException;
591    
592        /**
593         * Sends the body to the default endpoint and returns the result content
594         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
595         * <br/><br/>
596         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
597         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
598         * the caused exception wrapped.
599         *
600         * @param body the payload to send
601         * @param type the expected response type
602         * @return the result (see class javadoc)
603         * @throws CamelExecutionException if the processing of the exchange failed
604         */
605        <T> T requestBody(Object body, Class<T> type) throws CamelExecutionException;
606    
607        /**
608         * Send the body to an endpoint returning any result output body.
609         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
610         * <br/><br/>
611         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
612         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
613         * the caused exception wrapped.
614         *
615         * @param endpoint the Endpoint to send to
616         * @param body     the payload
617         * @return the result (see class javadoc)
618         * @throws CamelExecutionException if the processing of the exchange failed
619         */
620        Object requestBody(Endpoint endpoint, Object body) throws CamelExecutionException;
621    
622        /**
623         * Send the body to an endpoint returning any result output body.
624         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
625         * <br/><br/>
626         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
627         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
628         * the caused exception wrapped.
629         *
630         * @param endpoint the Endpoint to send to
631         * @param body     the payload
632         * @param type     the expected response type
633         * @return the result (see class javadoc)
634         * @throws CamelExecutionException if the processing of the exchange failed
635         */
636        <T> T requestBody(Endpoint endpoint, Object body, Class<T> type) throws CamelExecutionException;
637    
638        /**
639         * Send the body to an endpoint returning any result output body.
640         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
641         * <br/><br/>
642         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
643         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
644         * the caused exception wrapped.
645         *
646         * @param endpointUri the endpoint URI to send to
647         * @param body        the payload
648         * @return the result (see class javadoc)
649         * @throws CamelExecutionException if the processing of the exchange failed
650         */
651        Object requestBody(String endpointUri, Object body) throws CamelExecutionException;
652    
653        /**
654         * Send the body to an endpoint returning any result output body.
655         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
656         * <br/><br/>
657         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
658         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
659         * the caused exception wrapped.
660         *
661         * @param endpointUri the endpoint URI to send to
662         * @param body        the payload
663         * @param type        the expected response type
664         * @return the result (see class javadoc)
665         * @throws CamelExecutionException if the processing of the exchange failed
666         */
667        <T> T requestBody(String endpointUri, Object body, Class<T> type) throws CamelExecutionException;
668    
669        /**
670         * Sends the body to the default endpoint and returns the result content
671         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
672         * <br/><br/>
673         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
674         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
675         * the caused exception wrapped.
676         *
677         * @param body        the payload
678         * @param header      the header name
679         * @param headerValue the header value
680         * @return the result (see class javadoc)
681         * @throws CamelExecutionException if the processing of the exchange failed
682         */
683        Object requestBodyAndHeader(Object body, String header, Object headerValue) throws CamelExecutionException;
684    
685        /**
686         * Send the body to an endpoint returning any result output body.
687         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
688         * <br/><br/>
689         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
690         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
691         * the caused exception wrapped.
692         *
693         * @param endpoint    the Endpoint to send to
694         * @param body        the payload
695         * @param header      the header name
696         * @param headerValue the header value
697         * @return the result (see class javadoc)
698         * @throws CamelExecutionException if the processing of the exchange failed
699         */
700        Object requestBodyAndHeader(Endpoint endpoint, Object body, String header, Object headerValue) throws CamelExecutionException;
701    
702        /**
703         * Send the body to an endpoint returning any result output body.
704         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
705         * <br/><br/>
706         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
707         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
708         * the caused exception wrapped.
709         *
710         * @param endpoint    the Endpoint to send to
711         * @param body        the payload
712         * @param header      the header name
713         * @param headerValue the header value
714         * @param type        the expected response type
715         * @return the result (see class javadoc)
716         * @throws CamelExecutionException if the processing of the exchange failed
717         */
718        <T> T requestBodyAndHeader(Endpoint endpoint, Object body, String header, Object headerValue, Class<T> type) throws CamelExecutionException;
719    
720        /**
721         * Send the body to an endpoint returning any result output body.
722         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
723         * <br/><br/>
724         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
725         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
726         * the caused exception wrapped.
727         *
728         * @param endpointUri the endpoint URI to send to
729         * @param body        the payload
730         * @param header      the header name
731         * @param headerValue the header value
732         * @return the result (see class javadoc)
733         * @throws CamelExecutionException if the processing of the exchange failed
734         */
735        Object requestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue) throws CamelExecutionException;
736    
737        /**
738         * Send the body to an endpoint returning any result output body.
739         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
740         * <br/><br/>
741         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
742         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
743         * the caused exception wrapped.
744         *
745         * @param endpointUri the endpoint URI to send to
746         * @param body        the payload
747         * @param header      the header name
748         * @param headerValue the header value
749         * @param type        the expected response type
750         * @return the result (see class javadoc)
751         * @throws CamelExecutionException if the processing of the exchange failed
752         */
753        <T> T requestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue, Class<T> type) throws CamelExecutionException;
754    
755        /**
756         * Sends the body to an endpoint with the specified headers and header values.
757         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
758         * <br/><br/>
759         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
760         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
761         * the caused exception wrapped.
762         *
763         * @param endpointUri the endpoint URI to send to
764         * @param body the payload to send
765         * @param headers headers
766         * @return the result (see class javadoc)
767         * @throws CamelExecutionException if the processing of the exchange failed
768         */
769        Object requestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers) throws CamelExecutionException;
770    
771        /**
772         * Sends the body to an endpoint with the specified headers and header values.
773         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
774         * <br/><br/>
775         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
776         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
777         * the caused exception wrapped.
778         *
779         * @param endpointUri the endpoint URI to send to
780         * @param body the payload to send
781         * @param headers headers
782         * @param type the expected response type
783         * @return the result (see class javadoc)
784         * @throws CamelExecutionException if the processing of the exchange failed
785         */
786        <T> T requestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers, Class<T> type) throws CamelExecutionException;
787    
788        /**
789         * Sends the body to an endpoint with the specified headers and header values.
790         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
791         * <br/><br/>
792         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
793         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
794         * the caused exception wrapped.
795         *
796         * @param endpoint the endpoint URI to send to
797         * @param body the payload to send
798         * @param headers headers
799         * @return the result (see class javadoc)
800         * @throws CamelExecutionException if the processing of the exchange failed
801         */
802        Object requestBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers) throws CamelExecutionException;
803    
804        /**
805         * Sends the body to the default endpoint and returns the result content
806         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
807         * <br/><br/>
808         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
809         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
810         * the caused exception wrapped.
811         *
812         * @param body the payload to send
813         * @param headers headers
814         * @return the result (see class javadoc)
815         * @throws CamelExecutionException if the processing of the exchange failed
816         */
817        Object requestBodyAndHeaders(Object body, Map<String, Object> headers) throws CamelExecutionException;
818    
819        /**
820         * Sends the body to an endpoint with the specified headers and header values.
821         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
822         * <br/><br/>
823         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
824         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
825         * the caused exception wrapped.
826         *
827         * @param endpoint the endpoint URI to send to
828         * @param body the payload to send
829         * @param headers headers
830         * @param type the expected response type
831         * @return the result (see class javadoc)
832         * @throws CamelExecutionException if the processing of the exchange failed
833         */
834        <T> T requestBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers, Class<T> type) throws CamelExecutionException;
835    
836    
837        // Asynchronous methods
838        // -----------------------------------------------------------------------
839    
840        /**
841         * Sets a custom executor service to use for async messaging.
842         *
843         * @param executorService  the executor service.
844         */
845        void setExecutorService(ExecutorService executorService);
846    
847        /**
848         * Sends an asynchronous exchange to the given endpoint.
849         *
850         * @param endpointUri the endpoint URI to send the exchange to
851         * @param exchange    the exchange to send
852         * @return a handle to be used to get the response in the future
853         */
854        Future<Exchange> asyncSend(String endpointUri, Exchange exchange);
855    
856        /**
857         * Sends an asynchronous exchange to the given endpoint.
858         *
859         * @param endpointUri the endpoint URI to send the exchange to
860         * @param processor   the transformer used to populate the new exchange
861         * @return a handle to be used to get the response in the future
862         */
863        Future<Exchange> asyncSend(String endpointUri, Processor processor);
864    
865        /**
866         * Sends an asynchronous body to the given endpoint.
867         * Uses an {@link ExchangePattern#InOnly} message exchange pattern.
868         *
869         * @param endpointUri the endpoint URI to send the exchange to
870         * @param body        the body to send
871         * @return a handle to be used to get the response in the future
872         */
873        Future<Object> asyncSendBody(String endpointUri, Object body);
874    
875        /**
876         * Sends an asynchronous body to the given endpoint.
877         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
878         *
879         * @param endpointUri the endpoint URI to send the exchange to
880         * @param body        the body to send
881         * @return a handle to be used to get the response in the future
882         */
883        Future<Object> asyncRequestBody(String endpointUri, Object body);
884    
885        /**
886         * Sends an asynchronous body to the given endpoint.
887         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
888         *
889         * @param endpointUri the endpoint URI to send the exchange to
890         * @param body        the body to send
891         * @param header      the header name
892         * @param headerValue the header value
893         * @return a handle to be used to get the response in the future
894         */
895        Future<Object> asyncRequestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue);
896    
897        /**
898         * Sends an asynchronous body to the given endpoint.
899         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
900         *
901         * @param endpointUri the endpoint URI to send the exchange to
902         * @param body        the body to send
903         * @param headers     headers
904         * @return a handle to be used to get the response in the future
905         */
906        Future<Object> asyncRequestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers);
907    
908        /**
909         * Sends an asynchronous body to the given endpoint.
910         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
911         *
912         * @param endpointUri the endpoint URI to send the exchange to
913         * @param body        the body to send
914         * @param type        the expected response type
915         * @return a handle to be used to get the response in the future
916         */
917        <T> Future<T> asyncRequestBody(String endpointUri, Object body, Class<T> type);
918    
919        /**
920         * Sends an asynchronous body to the given endpoint.
921         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
922         *
923         * @param endpointUri the endpoint URI to send the exchange to
924         * @param body        the body to send
925         * @param header      the header name
926         * @param headerValue the header value
927         * @param type        the expected response type
928         * @return a handle to be used to get the response in the future
929         */
930        <T> Future<T> asyncRequestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue, Class<T> type);
931    
932        /**
933         * Sends an asynchronous body to the given endpoint.
934         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
935         *
936         * @param endpointUri the endpoint URI to send the exchange to
937         * @param body        the body to send
938         * @param headers     headers
939         * @param type        the expected response type
940         * @return a handle to be used to get the response in the future
941         */
942        <T> Future<T> asyncRequestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers, Class<T> type);
943    
944        /**
945         * Sends an asynchronous exchange to the given endpoint.
946         *
947         * @param endpoint    the endpoint to send the exchange to
948         * @param exchange    the exchange to send
949         * @return a handle to be used to get the response in the future
950         */
951        Future<Exchange> asyncSend(Endpoint endpoint, Exchange exchange);
952    
953        /**
954         * Sends an asynchronous exchange to the given endpoint.
955         *
956         * @param endpoint    the endpoint to send the exchange to
957         * @param processor   the transformer used to populate the new exchange
958         * @return a handle to be used to get the response in the future
959         */
960        Future<Exchange> asyncSend(Endpoint endpoint, Processor processor);
961    
962        /**
963         * Sends an asynchronous body to the given endpoint.
964         * Uses an {@link ExchangePattern#InOnly} message exchange pattern.
965         *
966         * @param endpoint    the endpoint to send the exchange to
967         * @param body        the body to send
968         * @return a handle to be used to get the response in the future
969         */
970        Future<Object> asyncSendBody(Endpoint endpoint, Object body);
971    
972        /**
973         * Sends an asynchronous body to the given endpoint.
974         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
975         *
976         * @param endpoint    the endpoint to send the exchange to
977         * @param body        the body to send
978         * @return a handle to be used to get the response in the future
979         */
980        Future<Object> asyncRequestBody(Endpoint endpoint, Object body);
981    
982        /**
983         * Sends an asynchronous body to the given endpoint.
984         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
985         *
986         * @param endpoint the endpoint to send the exchange to
987         * @param body        the body to send
988         * @param header      the header name
989         * @param headerValue the header value
990         * @return a handle to be used to get the response in the future
991         */
992        Future<Object> asyncRequestBodyAndHeader(Endpoint endpoint, Object body, String header, Object headerValue);
993    
994        /**
995         * Sends an asynchronous body to the given endpoint.
996         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
997         *
998         * @param endpoint    the endpoint to send the exchange to
999         * @param body        the body to send
1000         * @param headers     headers
1001         * @return a handle to be used to get the response in the future
1002         */
1003        Future<Object> asyncRequestBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers);
1004    
1005        /**
1006         * Sends an asynchronous body to the given endpoint.
1007         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
1008         *
1009         * @param endpoint    the endpoint to send the exchange to
1010         * @param body        the body to send
1011         * @param type        the expected response type
1012         * @return a handle to be used to get the response in the future
1013         */
1014        <T> Future<T> asyncRequestBody(Endpoint endpoint, Object body, Class<T> type);
1015    
1016        /**
1017         * Sends an asynchronous body to the given endpoint.
1018         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
1019         *
1020         * @param endpoint    the endpoint to send the exchange to
1021         * @param body        the body to send
1022         * @param header      the header name
1023         * @param headerValue the header value
1024         * @param type        the expected response type
1025         * @return a handle to be used to get the response in the future
1026         */
1027        <T> Future<T> asyncRequestBodyAndHeader(Endpoint endpoint, Object body, String header, Object headerValue, Class<T> type);
1028    
1029        /**
1030         * Sends an asynchronous body to the given endpoint.
1031         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
1032         *
1033         * @param endpoint    the endpoint to send the exchange to
1034         * @param body        the body to send
1035         * @param headers     headers
1036         * @param type        the expected response type
1037         * @return a handle to be used to get the response in the future
1038         */
1039        <T> Future<T> asyncRequestBodyAndHeaders(Endpoint endpoint, Object body, Map<String, Object> headers, Class<T> type);
1040    
1041        /**
1042         * Gets the response body from the future handle, will wait until the response is ready.
1043         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
1044         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
1045         * the caused exception wrapped.
1046         *
1047         * @param future      the handle to get the response
1048         * @param type        the expected response type
1049         * @return the result (see class javadoc)
1050         * @throws CamelExecutionException if the processing of the exchange failed
1051         */
1052        <T> T extractFutureBody(Future<Object> future, Class<T> type) throws CamelExecutionException;
1053    
1054        /**
1055         * Gets the response body from the future handle, will wait at most the given time for the response to be ready.
1056         * <p/><b>Notice:</b> that if the processing of the exchange failed with an Exception
1057         * it is thrown from this method as a {@link org.apache.camel.CamelExecutionException} with
1058         * the caused exception wrapped.
1059         *
1060         * @param future      the handle to get the response
1061         * @param timeout     the maximum time to wait
1062         * @param unit        the time unit of the timeout argument
1063         * @param type        the expected response type
1064         * @return the result (see class javadoc)
1065         * @throws java.util.concurrent.TimeoutException if the wait timed out
1066         * @throws CamelExecutionException if the processing of the exchange failed
1067         */
1068        <T> T extractFutureBody(Future<Object> future, long timeout, TimeUnit unit, Class<T> type) throws TimeoutException, CamelExecutionException;
1069    
1070        // Asynchronous methods with callback
1071        // -----------------------------------------------------------------------
1072    
1073        /**
1074         * Sends an asynchronous exchange to the given endpoint.
1075         *
1076         * @param endpointUri   the endpoint URI to send the exchange to
1077         * @param exchange      the exchange to send
1078         * @param onCompletion  callback invoked when exchange has been completed
1079         * @return a handle to be used to get the response in the future
1080         */
1081        Future<Exchange> asyncCallback(String endpointUri, Exchange exchange, Synchronization onCompletion);
1082    
1083        /**
1084         * Sends an asynchronous exchange to the given endpoint.
1085         *
1086         * @param endpoint      the endpoint to send the exchange to
1087         * @param exchange      the exchange to send
1088         * @param onCompletion  callback invoked when exchange has been completed
1089         * @return a handle to be used to get the response in the future
1090         */
1091        Future<Exchange> asyncCallback(Endpoint endpoint, Exchange exchange, Synchronization onCompletion);
1092    
1093        /**
1094         * Sends an asynchronous exchange to the given endpoint using a supplied processor.
1095         *
1096         * @param endpointUri   the endpoint URI to send the exchange to
1097         * @param processor     the transformer used to populate the new exchange
1098         * {@link Processor} to populate the exchange
1099         * @param onCompletion  callback invoked when exchange has been completed
1100         * @return a handle to be used to get the response in the future
1101         */
1102        Future<Exchange> asyncCallback(String endpointUri, Processor processor, Synchronization onCompletion);
1103    
1104        /**
1105         * Sends an asynchronous exchange to the given endpoint using a supplied processor.
1106         *
1107         * @param endpoint      the endpoint to send the exchange to
1108         * @param processor     the transformer used to populate the new exchange
1109         * {@link Processor} to populate the exchange
1110         * @param onCompletion  callback invoked when exchange has been completed
1111         * @return a handle to be used to get the response in the future
1112         */
1113        Future<Exchange> asyncCallback(Endpoint endpoint, Processor processor, Synchronization onCompletion);
1114    
1115        /**
1116         * Sends an asynchronous body to the given endpoint.
1117         * Uses an {@link ExchangePattern#InOnly} message exchange pattern.
1118         *
1119         * @param endpointUri   the endpoint URI to send the exchange to
1120         * @param body          the body to send
1121         * @param onCompletion  callback invoked when exchange has been completed
1122         * @return a handle to be used to get the response in the future
1123         */
1124        Future<Object> asyncCallbackSendBody(String endpointUri, Object body, Synchronization onCompletion);
1125    
1126        /**
1127         * Sends an asynchronous body to the given endpoint.
1128         * Uses an {@link ExchangePattern#InOnly} message exchange pattern.
1129         *
1130         * @param endpoint      the endpoint to send the exchange to
1131         * @param body          the body to send
1132         * @param onCompletion  callback invoked when exchange has been completed
1133         * @return a handle to be used to get the response in the future
1134         */
1135        Future<Object> asyncCallbackSendBody(Endpoint endpoint, Object body, Synchronization onCompletion);
1136    
1137        /**
1138         * Sends an asynchronous body to the given endpoint.
1139         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
1140         *
1141         * @param endpointUri   the endpoint URI to send the exchange to
1142         * @param body          the body to send
1143         * @param onCompletion  callback invoked when exchange has been completed
1144         * @return a handle to be used to get the response in the future
1145         */
1146        Future<Object> asyncCallbackRequestBody(String endpointUri, Object body, Synchronization onCompletion);
1147    
1148        /**
1149         * Sends an asynchronous body to the given endpoint.
1150         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
1151         *
1152         * @param endpoint      the endpoint to send the exchange to
1153         * @param body          the body to send
1154         * @param onCompletion  callback invoked when exchange has been completed
1155         * @return a handle to be used to get the response in the future
1156         */
1157        Future<Object> asyncCallbackRequestBody(Endpoint endpoint, Object body, Synchronization onCompletion);
1158    
1159    }