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