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: 727288 $
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 }