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 occured. 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 $Revision: 931444 $
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 *
079 * @param endpointUri the endpoint to receive from
080 * @return the returned exchange
081 */
082 Exchange receive(String endpointUri);
083
084 /**
085 * Receives from the endpoint, waiting until there is a response
086 *
087 * @param endpoint the endpoint to receive from
088 * @return the returned exchange
089 */
090 Exchange receive(Endpoint endpoint);
091
092 /**
093 * Receives from the endpoint, waiting until there is a response
094 * or the timeout occurs
095 *
096 * @param endpointUri the endpoint to receive from
097 * @param timeout timeout in millis to wait for a response
098 * @return the returned exchange, or <tt>null</tt> if no response
099 */
100 Exchange receive(String endpointUri, long timeout);
101
102 /**
103 * Receives from the endpoint, waiting until there is a response
104 * or the timeout occurs
105 *
106 * @param endpoint the endpoint to receive from
107 * @param timeout timeout in millis to wait for a response
108 * @return the returned exchange, or <tt>null</tt> if no response
109 */
110 Exchange receive(Endpoint endpoint, long timeout);
111
112 /**
113 * Receives from the endpoint, not waiting for a response if non exists.
114 *
115 * @param endpointUri the endpoint to receive from
116 * @return the returned exchange, or <tt>null</tt> if no response
117 */
118 Exchange receiveNoWait(String endpointUri);
119
120 /**
121 * Receives from the endpoint, not waiting for a response if non exists.
122 *
123 * @param endpoint the endpoint to receive from
124 * @return the returned exchange, or <tt>null</tt> if no response
125 */
126 Exchange receiveNoWait(Endpoint endpoint);
127
128 /**
129 * Receives from the endpoint, waiting until there is a response
130 *
131 * @param endpointUri the endpoint to receive from
132 * @return the returned response body
133 */
134 Object receiveBody(String endpointUri);
135
136 /**
137 * Receives from the endpoint, waiting until there is a response
138 *
139 * @param endpoint the endpoint to receive from
140 * @return the returned response body
141 */
142 Object receiveBody(Endpoint endpoint);
143
144 /**
145 * Receives from the endpoint, waiting until there is a response
146 * or the timeout occurs
147 *
148 * @param endpointUri the endpoint to receive from
149 * @param timeout timeout in millis to wait for a response
150 * @return the returned response body, or <tt>null</tt> if no response
151 */
152 Object receiveBody(String endpointUri, long timeout);
153
154 /**
155 * Receives from the endpoint, waiting until there is a response
156 * or the timeout occurs
157 *
158 * @param endpoint the endpoint to receive from
159 * @param timeout timeout in millis to wait for a response
160 * @return the returned response body, or <tt>null</tt> if no response
161 */
162 Object receiveBody(Endpoint endpoint, long timeout);
163
164 /**
165 * Receives from the endpoint, not waiting for a response if non exists.
166 *
167 * @param endpointUri the endpoint to receive from
168 * @return the returned response body, or <tt>null</tt> if no response
169 */
170 Object receiveBodyNoWait(String endpointUri);
171
172 /**
173 * Receives from the endpoint, not waiting for a response if non exists.
174 *
175 * @param endpoint the endpoint to receive from
176 * @return the returned response body, or <tt>null</tt> if no response
177 */
178 Object receiveBodyNoWait(Endpoint endpoint);
179
180 /**
181 * Receives from the endpoint, waiting until there is a response
182 *
183 * @param endpointUri the endpoint to receive from
184 * @param type the expected response type
185 * @return the returned response body
186 */
187 <T> T receiveBody(String endpointUri, Class<T> type);
188
189 /**
190 * Receives from the endpoint, waiting until there is a response
191 *
192 * @param endpoint the endpoint to receive from
193 * @param type the expected response type
194 * @return the returned response body
195 */
196 <T> T receiveBody(Endpoint endpoint, Class<T> type);
197
198 /**
199 * Receives from the endpoint, waiting until there is a response
200 * or the timeout occurs
201 *
202 * @param endpointUri the endpoint to receive from
203 * @param timeout timeout in millis to wait for a response
204 * @param type the expected response type
205 * @return the returned response body, or <tt>null</tt> if no response
206 */
207 <T> T receiveBody(String endpointUri, long timeout, Class<T> type);
208
209 /**
210 * Receives from the endpoint, waiting until there is a response
211 * or the timeout occurs
212 *
213 * @param endpoint the endpoint to receive from
214 * @param timeout timeout in millis to wait for a response
215 * @param type the expected response type
216 * @return the returned response body, or <tt>null</tt> if no response
217 */
218 <T> T receiveBody(Endpoint endpoint, long timeout, Class<T> type);
219
220 /**
221 * Receives from the endpoint, not waiting for a response if non exists.
222 *
223 * @param endpointUri the endpoint to receive from
224 * @param type the expected response type
225 * @return the returned response body, or <tt>null</tt> if no response
226 */
227 <T> T receiveBodyNoWait(String endpointUri, Class<T> type);
228
229 /**
230 * Receives from the endpoint, not waiting for a response if non exists.
231 *
232 * @param endpoint the endpoint to receive from
233 * @param type the expected response type
234 * @return the returned response body, or <tt>null</tt> if no response
235 */
236 <T> T receiveBodyNoWait(Endpoint endpoint, Class<T> type);
237
238 }