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
019/**
020 * Template for working with Camel and consuming {@link Message} instances in an
021 * {@link Exchange} from an {@link Endpoint}.
022 * <br/>
023 * <p/>This template is an implementation of the
024 * <a href="http://camel.apache.org/polling-consumer.html">Polling Consumer EIP</a>.
025 * This is <b>not</b> the <a href="http://camel.apache.org/event-driven-consumer.html">Event Driven Consumer EIP</a>.
026 * <br/>
027 * <p/>The {@link ConsumerTemplate} is <b>thread safe</b>.
028 * <br/>
029 * <p/><b>All</b> methods throws {@link RuntimeCamelException} if consuming of
030 * the {@link Exchange} failed and an Exception occurred. The <tt>getCause</tt>
031 * method on {@link RuntimeCamelException} returns the wrapper original caused
032 * exception.
033 * <br/>
034 * <p/>All the receive<b>Body</b> methods will return the content according to this strategy
035 * <ul>
036 *   <li>throws {@link RuntimeCamelException} as stated above</li>
037 *   <li>The <tt>fault.body</tt> if there is a fault message set and its not <tt>null</tt></li>
038 *   <li>The <tt>out.body</tt> if there is a out message set and its not <tt>null</tt></li>
039 *   <li>The <tt>in.body</tt></li>
040 * </ul>
041 * <br/>
042 * <p/>Before using the template it must be started.
043 * And when you are done using the template, make sure to {@link #stop()} the template.
044 * <br/>
045 * <p/><b>Important note on usage:</b> See this
046 * <a href="http://camel.apache.org/why-does-camel-use-too-many-threads-with-producertemplate.html">FAQ entry</a>
047 * before using, it applies to this {@link ConsumerTemplate} as well.
048 *
049 * @see ProducerTemplate
050 * @see FluentProducerTemplate
051 */
052public interface ConsumerTemplate extends Service {
053
054    /**
055     * Get the {@link CamelContext}
056     *
057     * @return camelContext the Camel context
058     */
059    CamelContext getCamelContext();
060
061    // Configuration methods
062    // -----------------------------------------------------------------------
063
064    /**
065     * Gets the maximum cache size used.
066     *
067     * @return the maximum cache size
068     */
069    int getMaximumCacheSize();
070
071    /**
072     * Sets a custom maximum cache size.
073     *
074     * @param maximumCacheSize the custom maximum cache size
075     */
076    void setMaximumCacheSize(int maximumCacheSize);
077
078    /**
079     * Gets an approximated size of the current cached resources in the backing cache pools.
080     *
081     * @return the size of current cached resources
082     */
083    int getCurrentCacheSize();
084
085    /**
086     * Cleanup the cache (purging stale entries)
087     */
088    void cleanUp();
089
090    // Synchronous methods
091    // -----------------------------------------------------------------------
092
093    /**
094     * Receives from the endpoint, waiting until there is a response
095     * <p/>
096     * <b>Important:</b> See {@link #doneUoW(Exchange)}
097     *
098     * @param endpointUri the endpoint to receive from
099     * @return the returned exchange
100     */
101    Exchange receive(String endpointUri);
102
103    /**
104     * Receives from the endpoint, waiting until there is a response.
105     * <p/>
106     * <b>Important:</b> See {@link #doneUoW(Exchange)}
107     *
108     * @param endpoint the endpoint to receive from
109     * @return the returned exchange
110     * @see #doneUoW(Exchange)
111     */
112    Exchange receive(Endpoint endpoint);
113
114    /**
115     * Receives from the endpoint, waiting until there is a response
116     * or the timeout occurs
117     * <p/>
118     * <b>Important:</b> See {@link #doneUoW(Exchange)}
119     *
120     * @param endpointUri the endpoint to receive from
121     * @param timeout     timeout in millis to wait for a response
122     * @return the returned exchange, or <tt>null</tt> if no response
123     * @see #doneUoW(Exchange)
124     */
125    Exchange receive(String endpointUri, long timeout);
126
127    /**
128     * Receives from the endpoint, waiting until there is a response
129     * or the timeout occurs
130     * <p/>
131     * <b>Important:</b> See {@link #doneUoW(Exchange)}
132     *
133     * @param endpoint the endpoint to receive from
134     * @param timeout  timeout in millis to wait for a response
135     * @return the returned exchange, or <tt>null</tt> if no response
136     * @see #doneUoW(Exchange)
137     */
138    Exchange receive(Endpoint endpoint, long timeout);
139
140    /**
141     * Receives from the endpoint, not waiting for a response if non exists.
142     * <p/>
143     * <b>Important:</b> See {@link #doneUoW(Exchange)}
144     *
145     * @param endpointUri the endpoint to receive from
146     * @return the returned exchange, or <tt>null</tt> if no response
147     */
148    Exchange receiveNoWait(String endpointUri);
149
150    /**
151     * Receives from the endpoint, not waiting for a response if non exists.
152     * <p/>
153     * <b>Important:</b> See {@link #doneUoW(Exchange)}
154     *
155     * @param endpoint the endpoint to receive from
156     * @return the returned exchange, or <tt>null</tt> if no response
157     */
158    Exchange receiveNoWait(Endpoint endpoint);
159
160    /**
161     * Receives from the endpoint, waiting until there is a response
162     *
163     * @param endpointUri the endpoint to receive from
164     * @return the returned response body
165     */
166    Object receiveBody(String endpointUri);
167
168    /**
169     * Receives from the endpoint, waiting until there is a response
170     *
171     * @param endpoint the endpoint to receive from
172     * @return the returned response body
173     */
174    Object receiveBody(Endpoint endpoint);
175
176    /**
177     * Receives from the endpoint, waiting until there is a response
178     * or the timeout occurs
179     *
180     * @param endpointUri the endpoint to receive from
181     * @param timeout     timeout in millis to wait for a response
182     * @return the returned response body, or <tt>null</tt> if no response
183     */
184    Object receiveBody(String endpointUri, long timeout);
185
186    /**
187     * Receives from the endpoint, waiting until there is a response
188     * or the timeout occurs
189     *
190     * @param endpoint the endpoint to receive from
191     * @param timeout  timeout in millis to wait for a response
192     * @return the returned response body, or <tt>null</tt> if no response
193     */
194    Object receiveBody(Endpoint endpoint, long timeout);
195
196    /**
197     * Receives from the endpoint, not waiting for a response if non exists.
198     *
199     * @param endpointUri the endpoint to receive from
200     * @return the returned response body, or <tt>null</tt> if no response
201     */
202    Object receiveBodyNoWait(String endpointUri);
203
204    /**
205     * Receives from the endpoint, not waiting for a response if non exists.
206     *
207     * @param endpoint the endpoint to receive from
208     * @return the returned response body, or <tt>null</tt> if no response
209     */
210    Object receiveBodyNoWait(Endpoint endpoint);
211
212    /**
213     * Receives from the endpoint, waiting until there is a response
214     *
215     * @param endpointUri the endpoint to receive from
216     * @param type        the expected response type
217     * @return the returned response body
218     */
219    <T> T receiveBody(String endpointUri, Class<T> type);
220
221    /**
222     * Receives from the endpoint, waiting until there is a response
223     *
224     * @param endpoint the endpoint to receive from
225     * @param type     the expected response type
226     * @return the returned response body
227     */
228    <T> T receiveBody(Endpoint endpoint, Class<T> type);
229
230    /**
231     * Receives from the endpoint, waiting until there is a response
232     * or the timeout occurs
233     *
234     * @param endpointUri the endpoint to receive from
235     * @param timeout     timeout in millis to wait for a response
236     * @param type        the expected response type
237     * @return the returned response body, or <tt>null</tt> if no response
238     */
239    <T> T receiveBody(String endpointUri, long timeout, Class<T> type);
240
241    /**
242     * Receives from the endpoint, waiting until there is a response
243     * or the timeout occurs
244     *
245     * @param endpoint the endpoint to receive from
246     * @param timeout  timeout in millis to wait for a response
247     * @param type     the expected response type
248     * @return the returned response body, or <tt>null</tt> if no response
249     */
250    <T> T receiveBody(Endpoint endpoint, long timeout, Class<T> type);
251
252    /**
253     * Receives from the endpoint, not waiting for a response if non exists.
254     *
255     * @param endpointUri the endpoint to receive from
256     * @param type        the expected response type
257     * @return the returned response body, or <tt>null</tt> if no response
258     */
259    <T> T receiveBodyNoWait(String endpointUri, Class<T> type);
260
261    /**
262     * Receives from the endpoint, not waiting for a response if non exists.
263     *
264     * @param endpoint the endpoint to receive from
265     * @param type     the expected response type
266     * @return the returned response body, or <tt>null</tt> if no response
267     */
268    <T> T receiveBodyNoWait(Endpoint endpoint, Class<T> type);
269
270    /**
271     * If you have used any of the <tt>receive</tt> methods which returns a {@link Exchange} type
272     * then you need to invoke this method when you are done using the returned {@link Exchange}.
273     * <p/>
274     * This is needed to ensure any {@link org.apache.camel.spi.Synchronization} works is being executed.
275     * For example if you consumed from a file endpoint, then the consumed file is only moved/delete when
276     * you done the {@link Exchange}.
277     * <p/>
278     * Note for all the other <tt>receive</tt> methods which does <b>not</b> return a {@link Exchange} type,
279     * the done has been executed automatic by Camel itself.
280     *
281     * @param exchange  the exchange
282     */
283    void doneUoW(Exchange exchange);
284
285}