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 /**
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 */
051 public 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 }