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    }