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 */
017package org.apache.camel;
018
019import java.util.concurrent.Future;
020import java.util.function.Supplier;
021
022/**
023 * Template for working with Camel and sending {@link Message} instances in an
024 * {@link Exchange} to an {@link Endpoint} using a <i>fluent</i> build style.
025 * <br/>
026 * <p/><b>Important:</b> Read the javadoc of each method carefully to ensure the behavior of the method is understood.
027 * Some methods is for <tt>InOnly</tt>, others for <tt>InOut</tt> MEP. And some methods throws
028 * {@link org.apache.camel.CamelExecutionException} while others stores any thrown exception on the returned
029 * {@link Exchange}.
030 * <br/>
031 * <p/>The {@link FluentProducerTemplate} is <b>thread safe</b>.
032 * <br/>
033 * <p/>All the methods which sends a message may throw {@link FailedToCreateProducerException} in
034 * case the {@link Producer} could not be created. Or a {@link NoSuchEndpointException} if the endpoint could
035 * not be resolved. There may be other related exceptions being thrown which occurs <i>before</i> the {@link Producer}
036 * has started sending the message.
037 * <br/>
038 * <p/>All the send or request methods will return the content according to this strategy:
039 * <ul>
040 *   <li>throws {@link org.apache.camel.CamelExecutionException} if processing failed <i>during</i> routing
041 *       with the caused exception wrapped</li>
042 *   <li>The <tt>fault.body</tt> if there is a fault message set and its not <tt>null</tt></li>
043 *   <li>Either <tt>IN</tt> or <tt>OUT</tt> body according to the message exchange pattern. If the pattern is
044 *   Out capable then the <tt>OUT</tt> body is returned, otherwise <tt>IN</tt>.
045 * </ul>
046 * <br/>
047 * <p/>Before using the template it must be started.
048 * And when you are done using the template, make sure to {@link #stop()} the template.
049 * <br/>
050 * <p/><b>Important note on usage:</b> See this
051 * <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">FAQ entry</a>
052 * before using.
053 *
054 * @see ProducerTemplate
055 * @see ConsumerTemplate
056 */
057public interface FluentProducerTemplate extends Service {
058
059    /**
060     * Get the {@link CamelContext}
061     *
062     * @return camelContext the Camel context
063     */
064    CamelContext getCamelContext();
065
066    // Configuration methods
067    // -----------------------------------------------------------------------
068
069    /**
070     * Gets the maximum cache size used in the backing cache pools.
071     *
072     * @return the maximum cache size
073     */
074    int getMaximumCacheSize();
075
076    /**
077     * Sets a custom maximum cache size to use in the backing cache pools.
078     *
079     * @param maximumCacheSize the custom maximum cache size
080     */
081    void setMaximumCacheSize(int maximumCacheSize);
082
083    /**
084     * Gets an approximated size of the current cached resources in the backing cache pools.
085     *
086     * @return the size of current cached resources
087     */
088    int getCurrentCacheSize();
089
090    /**
091     * Get the default endpoint to use if none is specified
092     *
093     * @return the default endpoint instance
094     */
095    Endpoint getDefaultEndpoint();
096
097    /**
098     * Sets the default endpoint to use if none is specified
099     *
100     * @param defaultEndpoint the default endpoint instance
101     */
102    void setDefaultEndpoint(Endpoint defaultEndpoint);
103
104    /**
105     * Sets the default endpoint uri to use if none is specified
106     *
107     *  @param endpointUri the default endpoint uri
108     */
109    void setDefaultEndpointUri(String endpointUri);
110
111    /**
112     * Sets whether the {@link org.apache.camel.spi.EventNotifier} should be
113     * used by this {@link ProducerTemplate} to send events about the {@link Exchange}
114     * being sent.
115     * <p/>
116     * By default this is enabled.
117     *
118     * @param enabled <tt>true</tt> to enable, <tt>false</tt> to disable.
119     */
120    void setEventNotifierEnabled(boolean enabled);
121
122    /**
123     * Whether the {@link org.apache.camel.spi.EventNotifier} should be
124     * used by this {@link ProducerTemplate} to send events about the {@link Exchange}
125     * being sent.
126     *
127     * @return <tt>true</tt> if enabled, <tt>false</tt> otherwise
128     */
129    boolean isEventNotifierEnabled();
130
131    /**
132     * Cleanup the cache (purging stale entries)
133     */
134    void cleanUp();
135
136    // Fluent methods
137    // -----------------------------------------------------------------------
138
139    /**
140     * Remove the body and headers.
141     */
142    FluentProducerTemplate clearAll();
143
144    /**
145     * Set the header
146     *
147     * @param key the key of the header
148     * @param value the value of the header
149     */
150    FluentProducerTemplate withHeader(String key, Object value);
151
152    /**
153     * Remove the headers.
154     */
155    FluentProducerTemplate clearHeaders();
156
157    /**
158     * Set the message body
159     *
160     * @param body the body
161     */
162    FluentProducerTemplate withBody(Object body);
163
164    /**
165     * Set the message body after converting it to the given type
166     *
167     * @param body the body
168     * @param type the type which the body should be converted to
169     */
170    FluentProducerTemplate withBodyAs(Object body, Class<?> type);
171
172    /**
173     * Remove the body.
174     */
175    FluentProducerTemplate clearBody();
176
177    /**
178     * To customize the producer template for advanced usage like to set the
179     * executor service to use.
180     *
181     * <pre>
182     * {@code
183     * FluentProducerTemplate.on(context)
184     *     .withTemplateCustomizer(
185     *         template -> {
186     *             template.setExecutorService(myExecutor);
187     *             template.setMaximumCacheSize(10);
188     *         }
189     *      )
190     *     .withBody("the body")
191     *     .to("direct:start")
192     *     .request()}
193     * </pre>
194     *
195     * Note that it is invoked only once.
196     *
197     * @param templateCustomizer the customizer
198     */
199    FluentProducerTemplate withTemplateCustomizer(java.util.function.Consumer<ProducerTemplate> templateCustomizer);
200
201    /**
202     * Set the exchange to use for send.
203     *
204     * @param exchange the exchange
205     */
206    FluentProducerTemplate withExchange(Exchange exchange);
207
208    /**
209     * Set the exchangeSupplier which will be invoke to get the exchange to be
210     * used for send.
211     *
212     * @param exchangeSupplier the supplier
213     */
214    FluentProducerTemplate withExchange(Supplier<Exchange> exchangeSupplier);
215
216    /**
217     * Set the processor to use for send/request.
218     *
219     * <pre>
220     * {@code
221     * FluentProducerTemplate.on(context)
222     *     .withProcessor(
223     *         exchange -> {
224     *             exchange.getIn().setHeader("Key1", "Val1");
225     *             exchange.getIn().setHeader("Key2", "Val2");
226     *             exchange.getIn().setBody("the body");
227     *         }
228     *      )
229     *     .to("direct:start")
230     *     .request()}
231     * </pre>
232     *
233     * @param processor 
234     */
235    FluentProducerTemplate withProcessor(Processor processor);
236
237    /**
238     * Set the processorSupplier which will be invoke to get the processor to be
239     * used for send/request.
240     *
241     * @param processorSupplier the supplier
242     */
243    FluentProducerTemplate withProcessor(Supplier<Processor> processorSupplier);
244
245    /**
246     * Endpoint to send to
247     *
248     * @param endpointUri the endpoint URI to send to
249     */
250    FluentProducerTemplate to(String endpointUri);
251
252    /**
253     * Endpoint to send to
254     *
255     * @param endpoint the endpoint to send to
256     */
257    FluentProducerTemplate to(Endpoint endpoint);
258
259    /**
260     * Send to an endpoint (InOut) returning any result output body.
261     *
262     * @return the result
263     * @throws CamelExecutionException is thrown if error occurred
264     */
265    Object request() throws CamelExecutionException;
266
267    /**
268     * Send to an endpoint (InOut).
269     *
270     * @param type the expected response type
271     * @return the result
272     * @throws CamelExecutionException is thrown if error occurred
273     */
274    <T> T request(Class<T> type) throws CamelExecutionException;
275
276    /**
277     * Sends asynchronously to the given endpoint (InOut).
278     *
279     * @return a handle to be used to get the response in the future
280     */
281    Future<Object> asyncRequest();
282
283    /**
284     * Sends asynchronously to the given endpoint (InOut).
285     *
286     * @param type the expected response type
287     * @return a handle to be used to get the response in the future
288     */
289    <T> Future<T> asyncRequest(Class<T> type);
290
291    /**
292     * Send to an endpoint (InOnly)
293     *
294     * @throws CamelExecutionException is thrown if error occurred
295     */
296    Exchange send() throws CamelExecutionException;
297
298    /**
299     * Sends asynchronously to the given endpoint (InOnly).
300     *
301     * @return a handle to be used to get the response in the future
302     */
303    Future<Exchange> asyncSend();
304}