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