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     *
039     * @version $Revision: 62373 $
040     */
041    public interface ProducerTemplate<E extends Exchange> extends Service {
042    
043        /**
044         * Sends the exchange to the default endpoint
045         *
046         * @param exchange the exchange to send
047         * @return the returned exchange
048         */
049        E send(E exchange);
050    
051        /**
052         * Sends an exchange to the default endpoint using a supplied processor
053         *
054         * @param processor the transformer used to populate the new exchange
055         * {@link Processor} to populate the exchange
056         * @return the returned exchange
057         */
058        E send(Processor processor);
059    
060        /**
061         * Sends the body to the default endpoint and returns the result content
062         *
063         * @param body the payload to send
064         * @return the result (see class javadoc)
065         */
066        Object sendBody(Object body);
067    
068        /**
069         * Sends the body to the default endpoint with a specified header and header
070         * value
071         *
072         * @param body        the payload to send
073         * @param header      the header name
074         * @param headerValue the header value
075         * @return the result (see class javadoc)
076         */
077        Object sendBodyAndHeader(Object body, String header, Object headerValue);
078    
079        /**
080         * Sends the body to the default endpoint with the specified headers and
081         * header values
082         *
083         * @param body the payload to send
084         * @param headers      the headers
085         * @return the result (see class javadoc)
086         */
087        Object sendBodyAndHeaders(Object body, Map<String, Object> headers);
088    
089        // Allow sending to arbitrary endpoints
090        // -----------------------------------------------------------------------
091    
092        /**
093         * Sends the exchange to the given endpoint
094         *
095         * @param endpointUri the endpoint URI to send the exchange to
096         * @param exchange    the exchange to send
097         * @return the returned exchange
098         */
099        E send(String endpointUri, E exchange);
100    
101        /**
102         * Sends an exchange to an endpoint using a supplied processor
103         *
104         * @param endpointUri the endpoint URI to send the exchange to
105         * @param processor   the transformer used to populate the new exchange
106         * {@link Processor} to populate the exchange
107         * @return the returned exchange
108         */
109        E send(String endpointUri, Processor processor);
110    
111        /**
112         * Sends an exchange to an endpoint using a supplied processor
113         *
114         * @param endpointUri the endpoint URI to send the exchange to
115         * @param pattern     the message {@link ExchangePattern} such as
116         *                    {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
117         * @param processor   the transformer used to populate the new exchange
118         * {@link Processor} to populate the exchange
119         * @return the returned exchange
120         */
121        E send(String endpointUri, ExchangePattern pattern, Processor processor);
122    
123        /**
124         * Sends an exchange to an endpoint using a supplied processor
125         *
126         * @param endpointUri the endpoint URI to send the exchange to
127         * @param processor   the transformer used to populate the new exchange
128         * {@link Processor} to populate the exchange.
129         * @param callback    the callback will be called when the exchange is completed.
130         * @return the returned exchange
131         */
132        E send(String endpointUri, Processor processor, AsyncCallback callback);
133    
134        /**
135         * Sends the exchange to the given endpoint
136         *
137         * @param endpoint the endpoint to send the exchange to
138         * @param exchange the exchange to send
139         * @return the returned exchange
140         */
141        E send(Endpoint<E> endpoint, E exchange);
142    
143        /**
144         * Sends an exchange to an endpoint using a supplied processor
145         *
146         * @param endpoint  the endpoint to send the exchange to
147         * @param processor the transformer used to populate the new exchange
148         * {@link Processor} to populate the exchange
149         * @return the returned exchange
150         */
151        E send(Endpoint<E> endpoint, Processor processor);
152    
153        /**
154         * Sends an exchange to an endpoint using a supplied processor
155         *
156         * @param endpoint  the endpoint to send the exchange to
157         * @param pattern   the message {@link ExchangePattern} such as
158         *                  {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
159         * @param processor the transformer used to populate the new exchange
160         * {@link Processor} to populate the exchange
161         * @return the returned exchange
162         */
163        E send(Endpoint<E> endpoint, ExchangePattern pattern, Processor processor);
164    
165        /**
166         * Sends an exchange to an endpoint using a supplied processor
167         *
168         * @param endpoint  the endpoint to send the exchange to
169         * @param processor the transformer used to populate the new exchange
170         * {@link Processor} to populate the exchange.
171         * @param callback  the callback will be called when the exchange is completed.
172         * @return the returned exchange
173         */
174        E send(Endpoint<E> endpoint, Processor processor, AsyncCallback callback);
175    
176        /**
177         * Send the body to an endpoint returning any result output body
178         *
179         * @param endpoint   the endpoint to send the exchange to
180         * @param body       the payload
181         * @return the result (see class javadoc)
182         */
183        Object sendBody(Endpoint<E> endpoint, Object body);
184    
185        /**
186         * Send the body to an endpoint returning any result output body
187         *
188         * @param endpointUri   the endpoint URI to send the exchange to
189         * @param body          the payload
190         * @return the result (see class javadoc)
191         */
192        Object sendBody(String endpointUri, Object body);
193    
194        /**
195         * Send the body to an endpoint with the given {@link ExchangePattern}
196         * returning any result output body
197         *
198         * @param endpoint      the endpoint to send the exchange to
199         * @param body          the payload
200         * @param pattern       the message {@link ExchangePattern} such as
201         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
202         * @return the result (see class javadoc)
203         */
204        Object sendBody(Endpoint<E> endpoint, ExchangePattern pattern, Object body);
205    
206        /**
207         * Send the body to an endpoint returning any result output body
208         *
209         * @param endpointUri   the endpoint URI to send the exchange to
210         * @param pattern       the message {@link ExchangePattern} such as
211         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
212         * @param body          the payload
213         * @return the result (see class javadoc)
214         */
215        Object sendBody(String endpointUri, ExchangePattern pattern, Object body);
216    
217        /**
218         * Sends the body to an endpoint with a specified header and header value
219         *
220         * @param endpointUri the endpoint URI to send to
221         * @param body the payload to send
222         * @param header the header name
223         * @param headerValue the header value
224         * @return the result (see class javadoc)
225         */
226        Object sendBodyAndHeader(String endpointUri, Object body, String header,
227                                        Object headerValue);
228    
229        /**
230         * Sends the body to an endpoint with a specified header and header value
231         *
232         * @param endpoint the Endpoint to send to
233         * @param body the payload to send
234         * @param header the header name
235         * @param headerValue the header value
236         * @return the result (see class javadoc)
237         */
238        Object sendBodyAndHeader(Endpoint<E> endpoint, Object body, String header,
239                                        Object headerValue);
240    
241        /**
242         * Sends the body to an endpoint with a specified header and header value
243         *
244         * @param endpoint the Endpoint to send to
245         * @param pattern the message {@link ExchangePattern} such as
246         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
247         * @param body the payload to send
248         * @param header the header name
249         * @param headerValue the header value
250         * @return the result (see class javadoc)
251         */
252        Object sendBodyAndHeader(Endpoint<E> endpoint, ExchangePattern pattern, Object body, String header,
253                                        Object headerValue);
254    
255        /**
256         * Sends the body to an endpoint with a specified header and header value
257         *
258         * @param endpoint the Endpoint URI to send to
259         * @param pattern the message {@link ExchangePattern} such as
260         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
261         * @param body the payload to send
262         * @param header the header name
263         * @param headerValue the header value
264         * @return the result (see class javadoc)
265         */
266        Object sendBodyAndHeader(String endpoint, ExchangePattern pattern, Object body, String header,
267                                        Object headerValue);
268    
269        /**
270         * Sends the body to an endpoint with the specified headers and header
271         * values
272         *
273         * @param endpointUri the endpoint URI to send to
274         * @param body the payload to send
275         * @param headers headers
276         * @return the result (see class javadoc)
277         */
278        Object sendBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers);
279    
280        /**
281         * Sends the body to an endpoint with the specified headers and header
282         * values
283         *
284         * @param endpoint the endpoint URI to send to
285         * @param body the payload to send
286         * @param headers headers
287         * @return the result (see class javadoc)
288         */
289        Object sendBodyAndHeaders(Endpoint<E> endpoint, Object body, Map<String, Object> headers);
290    
291        /**
292         * Sends the body to an endpoint with the specified headers and header
293         * values
294         *
295         * @param endpointUri the endpoint URI to send to
296         * @param pattern the message {@link ExchangePattern} such as
297         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
298         * @param body the payload to send
299         * @param headers headers
300         * @return the result (see class javadoc)
301         */
302        Object sendBodyAndHeaders(String endpointUri, ExchangePattern pattern, Object body,
303                                  Map<String, Object> headers);
304    
305        /**
306         * Sends the body to an endpoint with the specified headers and header
307         * values
308         *
309         * @param endpoint the endpoint URI to send to
310         * @param pattern the message {@link ExchangePattern} such as
311         *   {@link ExchangePattern#InOnly} or {@link ExchangePattern#InOut}
312         * @param body the payload to send
313         * @param headers headers
314         * @return the result (see class javadoc)
315         */
316        Object sendBodyAndHeaders(Endpoint<E> endpoint, ExchangePattern pattern, Object body,
317                                  Map<String, Object> headers);
318    
319    
320        // Methods using an InOut ExchangePattern
321        // -----------------------------------------------------------------------
322    
323        /**
324         * Sends an exchange to an endpoint using a supplied processor
325         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
326         *
327         * @param endpoint  the Endpoint to send to
328         * @param processor the processor which will populate the exchange before sending
329         * @return the result (see class javadoc)
330         */
331        E request(Endpoint<E> endpoint, Processor processor);
332    
333        /**
334         * Sends an exchange to an endpoint using a supplied processor
335         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
336         *
337         * @param endpointUri the endpoint URI to send to
338         * @param processor the processor which will populate the exchange before sending
339         * @return the result (see class javadoc)
340         */
341        Exchange request(String endpointUri, Processor processor);
342    
343        /**
344         * Send the body to an endpoint returning any result output body.
345         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
346         *
347         * @param endpoint the Endpoint to send to
348         * @param body     the payload
349         * @return the result (see class javadoc)
350         */
351        Object requestBody(Endpoint<E> endpoint, Object body);
352    
353        /**
354         * Send the body to an endpoint returning any result output body.
355         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
356         *
357         * @param endpointUri the endpoint URI to send to
358         * @param body        the payload
359         * @return the result (see class javadoc)
360         */
361        Object requestBody(String endpointUri, Object body);
362    
363        /**
364         * Send the body to an endpoint returning any result output body.
365         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
366         *
367         * @param endpoint    the Endpoint to send to
368         * @param body        the payload
369         * @param header      the header name
370         * @param headerValue the header value
371         * @return the result (see class javadoc)
372         */
373        Object requestBodyAndHeader(Endpoint<E> endpoint, Object body, String header, Object headerValue);
374    
375        /**
376         * Send the body to an endpoint returning any result output body.
377         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
378         *
379         * @param endpointUri the endpoint URI to send to
380         * @param body        the payload
381         * @param header      the header name
382         * @param headerValue the header value
383         * @return the result (see class javadoc)
384         */
385        Object requestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue);
386    
387        /**
388         * Sends the body to an endpoint with the specified headers and header
389         * values.
390         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
391         *
392         * @param endpointUri the endpoint URI to send to
393         * @param body the payload to send
394         * @param headers headers
395         * @return the result (see class javadoc)
396         */
397        Object requestBodyAndHeaders(String endpointUri, Object body, Map<String, Object> headers);
398    
399        /**
400         * Sends the body to an endpoint with the specified headers and header
401         * values.
402         * Uses an {@link ExchangePattern#InOut} message exchange pattern.
403         *
404         * @param endpoint the endpoint URI to send to
405         * @param body the payload to send
406         * @param headers headers
407         * @return the result (see class javadoc)
408         */
409        Object requestBodyAndHeaders(Endpoint<E> endpoint, Object body, Map<String, Object> headers);
410    }