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 * @version 
050 */
051public interface ConsumerTemplate extends Service {
052
053    /**
054     * Get the {@link CamelContext}
055     *
056     * @return camelContext the Camel context
057     */
058    CamelContext getCamelContext();
059
060    // Configuration methods
061    // -----------------------------------------------------------------------
062
063    /**
064     * Gets the maximum cache size used.
065     *
066     * @return the maximum cache size
067     */
068    int getMaximumCacheSize();
069
070    /**
071     * Sets a custom maximum cache size.
072     *
073     * @param maximumCacheSize the custom maximum cache size
074     */
075    void setMaximumCacheSize(int maximumCacheSize);
076
077    /**
078     * Gets an approximated size of the current cached resources in the backing cache pools.
079     *
080     * @return the size of current cached resources
081     */
082    int getCurrentCacheSize();
083
084    // Synchronous methods
085    // -----------------------------------------------------------------------
086
087    /**
088     * Receives from the endpoint, waiting until there is a response
089     * <p/>
090     * <b>Important:</b> See {@link #doneUoW(Exchange)}
091     *
092     * @param endpointUri the endpoint to receive from
093     * @return the returned exchange
094     */
095    Exchange receive(String endpointUri);
096
097    /**
098     * Receives from the endpoint, waiting until there is a response.
099     * <p/>
100     * <b>Important:</b> See {@link #doneUoW(Exchange)}
101     *
102     * @param endpoint the endpoint to receive from
103     * @return the returned exchange
104     * @see #doneUoW(Exchange)
105     */
106    Exchange receive(Endpoint endpoint);
107
108    /**
109     * Receives from the endpoint, waiting until there is a response
110     * or the timeout occurs
111     * <p/>
112     * <b>Important:</b> See {@link #doneUoW(Exchange)}
113     *
114     * @param endpointUri the endpoint to receive from
115     * @param timeout     timeout in millis to wait for a response
116     * @return the returned exchange, or <tt>null</tt> if no response
117     * @see #doneUoW(Exchange)
118     */
119    Exchange receive(String endpointUri, long timeout);
120
121    /**
122     * Receives from the endpoint, waiting until there is a response
123     * or the timeout occurs
124     * <p/>
125     * <b>Important:</b> See {@link #doneUoW(Exchange)}
126     *
127     * @param endpoint the endpoint to receive from
128     * @param timeout  timeout in millis to wait for a response
129     * @return the returned exchange, or <tt>null</tt> if no response
130     * @see #doneUoW(Exchange)
131     */
132    Exchange receive(Endpoint endpoint, long timeout);
133
134    /**
135     * Receives from the endpoint, not waiting for a response if non exists.
136     * <p/>
137     * <b>Important:</b> See {@link #doneUoW(Exchange)}
138     *
139     * @param endpointUri the endpoint to receive from
140     * @return the returned exchange, or <tt>null</tt> if no response
141     */
142    Exchange receiveNoWait(String endpointUri);
143
144    /**
145     * Receives from the endpoint, not waiting for a response if non exists.
146     * <p/>
147     * <b>Important:</b> See {@link #doneUoW(Exchange)}
148     *
149     * @param endpoint the endpoint to receive from
150     * @return the returned exchange, or <tt>null</tt> if no response
151     */
152    Exchange receiveNoWait(Endpoint endpoint);
153
154    /**
155     * Receives from the endpoint, waiting until there is a response
156     *
157     * @param endpointUri the endpoint to receive from
158     * @return the returned response body
159     */
160    Object receiveBody(String endpointUri);
161
162    /**
163     * Receives from the endpoint, waiting until there is a response
164     *
165     * @param endpoint the endpoint to receive from
166     * @return the returned response body
167     */
168    Object receiveBody(Endpoint endpoint);
169
170    /**
171     * Receives from the endpoint, waiting until there is a response
172     * or the timeout occurs
173     *
174     * @param endpointUri the endpoint to receive from
175     * @param timeout     timeout in millis to wait for a response
176     * @return the returned response body, or <tt>null</tt> if no response
177     */
178    Object receiveBody(String endpointUri, long timeout);
179
180    /**
181     * Receives from the endpoint, waiting until there is a response
182     * or the timeout occurs
183     *
184     * @param endpoint the endpoint to receive from
185     * @param timeout  timeout in millis to wait for a response
186     * @return the returned response body, or <tt>null</tt> if no response
187     */
188    Object receiveBody(Endpoint endpoint, long timeout);
189
190    /**
191     * Receives from the endpoint, not waiting for a response if non exists.
192     *
193     * @param endpointUri the endpoint to receive from
194     * @return the returned response body, or <tt>null</tt> if no response
195     */
196    Object receiveBodyNoWait(String endpointUri);
197
198    /**
199     * Receives from the endpoint, not waiting for a response if non exists.
200     *
201     * @param endpoint the endpoint to receive from
202     * @return the returned response body, or <tt>null</tt> if no response
203     */
204    Object receiveBodyNoWait(Endpoint endpoint);
205
206    /**
207     * Receives from the endpoint, waiting until there is a response
208     *
209     * @param endpointUri the endpoint to receive from
210     * @param type        the expected response type
211     * @return the returned response body
212     */
213    <T> T receiveBody(String endpointUri, Class<T> type);
214
215    /**
216     * Receives from the endpoint, waiting until there is a response
217     *
218     * @param endpoint the endpoint to receive from
219     * @param type     the expected response type
220     * @return the returned response body
221     */
222    <T> T receiveBody(Endpoint endpoint, Class<T> type);
223
224    /**
225     * Receives from the endpoint, waiting until there is a response
226     * or the timeout occurs
227     *
228     * @param endpointUri the endpoint to receive from
229     * @param timeout     timeout in millis to wait for a response
230     * @param type        the expected response type
231     * @return the returned response body, or <tt>null</tt> if no response
232     */
233    <T> T receiveBody(String endpointUri, long timeout, Class<T> type);
234
235    /**
236     * Receives from the endpoint, waiting until there is a response
237     * or the timeout occurs
238     *
239     * @param endpoint the endpoint to receive from
240     * @param timeout  timeout in millis to wait for a response
241     * @param type     the expected response type
242     * @return the returned response body, or <tt>null</tt> if no response
243     */
244    <T> T receiveBody(Endpoint endpoint, long timeout, Class<T> type);
245
246    /**
247     * Receives from the endpoint, not waiting for a response if non exists.
248     *
249     * @param endpointUri the endpoint to receive from
250     * @param type        the expected response type
251     * @return the returned response body, or <tt>null</tt> if no response
252     */
253    <T> T receiveBodyNoWait(String endpointUri, Class<T> type);
254
255    /**
256     * Receives from the endpoint, not waiting for a response if non exists.
257     *
258     * @param endpoint the endpoint to receive from
259     * @param type     the expected response type
260     * @return the returned response body, or <tt>null</tt> if no response
261     */
262    <T> T receiveBodyNoWait(Endpoint endpoint, Class<T> type);
263
264    /**
265     * If you have used any of the <tt>receive</tt> methods which returns a {@link Exchange} type
266     * then you need to invoke this method when you are done using the returned {@link Exchange}.
267     * <p/>
268     * This is needed to ensure any {@link org.apache.camel.spi.Synchronization} works is being executed.
269     * For example if you consumed from a file endpoint, then the consumed file is only moved/delete when
270     * you done the {@link Exchange}.
271     * <p/>
272     * Note for all the other <tt>receive</tt> methods which does <b>not</b> return a {@link Exchange} type,
273     * the done has been executed automatic by Camel itself.
274     *
275     * @param exchange  the exchange
276     */
277    void doneUoW(Exchange exchange);
278
279}