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