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: 51492 $
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
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 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 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 endpoint, Object body, Map<String, Object> headers);
290
291
292 // Methods using an InOut ExchangePattern
293 // -----------------------------------------------------------------------
294
295 /**
296 * Send the body to an endpoint returning any result output body.
297 * Uses an {@link ExchangePattern#InOut} message exchange pattern.
298 *
299 * @param endpoint the Endpoint to send to
300 * @param processor the processor which will populate the exchange before sending
301 * @return the result (see class javadoc)
302 */
303 E request(Endpoint<E> endpoint, Processor processor);
304
305 /**
306 * Send the body to an endpoint returning any result output body.
307 * Uses an {@link ExchangePattern#InOut} message exchange pattern.
308 *
309 * @param endpoint the Endpoint to send to
310 * @param body the payload
311 * @return the result (see class javadoc)
312 */
313 Object requestBody(Endpoint<E> endpoint, Object body);
314
315 /**
316 * Send the body to an endpoint returning any result output body.
317 * Uses an {@link ExchangePattern#InOut} message exchange pattern.
318 *
319 * @param endpoint the Endpoint to send to
320 * @param body the payload
321 * @param header the header name
322 * @param headerValue the header value
323 * @return the result (see class javadoc)
324 */
325 Object requestBodyAndHeader(Endpoint<E> endpoint, Object body, String header, Object headerValue);
326
327 /**
328 * Send the body to an endpoint returning any result output body.
329 * Uses an {@link ExchangePattern#InOut} message exchange pattern.
330 *
331 * @param endpointUri the endpoint URI 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(String endpointUri, Processor processor);
336
337 /**
338 * Send the body to an endpoint returning any result output body.
339 * Uses an {@link ExchangePattern#InOut} message exchange pattern.
340 *
341 * @param endpointUri the endpoint URI to send to
342 * @param body the payload
343 * @return the result (see class javadoc)
344 */
345 Object requestBody(String endpointUri, Object body);
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 endpointUri the endpoint URI to send to
352 * @param body the payload
353 * @param header the header name
354 * @param headerValue the header value
355 * @return the result (see class javadoc)
356 */
357 Object requestBodyAndHeader(String endpointUri, Object body, String header, Object headerValue);
358
359 }