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: 759657 $
046 */
047 public interface ConsumerTemplate extends Service {
048
049 /**
050 * Receives from the endpoint, waiting until there is a response
051 *
052 * @param endpointUri the endpoint to receive from
053 * @return the returned exchange
054 */
055 Exchange receive(String endpointUri);
056
057 /**
058 * Receives from the endpoint, waiting until there is a response
059 *
060 * @param endpoint the endpoint to receive from
061 * @return the returned exchange
062 */
063 Exchange receive(Endpoint endpoint);
064
065 /**
066 * Receives from the endpoint, waiting until there is a response
067 * or the timeout occurs
068 *
069 * @param endpointUri the endpoint to receive from
070 * @param timeout timeout in millis to wait for a response
071 * @return the returned exchange, or <tt>null</tt> if no response
072 */
073 Exchange receive(String endpointUri, long timeout);
074
075 /**
076 * Receives from the endpoint, waiting until there is a response
077 * or the timeout occurs
078 *
079 * @param endpoint the endpoint to receive from
080 * @param timeout timeout in millis to wait for a response
081 * @return the returned exchange, or <tt>null</tt> if no response
082 */
083 Exchange receive(Endpoint endpoint, long timeout);
084
085 /**
086 * Receives from the endpoint, not waiting for a response if non exists.
087 *
088 * @param endpointUri the endpoint to receive from
089 * @return the returned exchange, or <tt>null</tt> if no response
090 */
091 Exchange receiveNoWait(String endpointUri);
092
093 /**
094 * Receives from the endpoint, not waiting for a response if non exists.
095 *
096 * @param endpoint the endpoint to receive from
097 * @return the returned exchange, or <tt>null</tt> if no response
098 */
099 Exchange receiveNoWait(Endpoint endpoint);
100
101 /**
102 * Receives from the endpoint, waiting until there is a response
103 *
104 * @param endpointUri the endpoint to receive from
105 * @return the returned response body
106 */
107 Object receiveBody(String endpointUri);
108
109 /**
110 * Receives from the endpoint, waiting until there is a response
111 *
112 * @param endpoint the endpoint to receive from
113 * @return the returned response body
114 */
115 Object receiveBody(Endpoint endpoint);
116
117 /**
118 * Receives from the endpoint, waiting until there is a response
119 * or the timeout occurs
120 *
121 * @param endpointUri the endpoint to receive from
122 * @param timeout timeout in millis to wait for a response
123 * @return the returned response body, or <tt>null</tt> if no response
124 */
125 Object receiveBody(String endpointUri, long timeout);
126
127 /**
128 * Receives from the endpoint, waiting until there is a response
129 * or the timeout occurs
130 *
131 * @param endpoint the endpoint to receive from
132 * @param timeout timeout in millis to wait for a response
133 * @return the returned response body, or <tt>null</tt> if no response
134 */
135 Object receiveBody(Endpoint endpoint, long timeout);
136
137 /**
138 * Receives from the endpoint, not waiting for a response if non exists.
139 *
140 * @param endpointUri the endpoint to receive from
141 * @return the returned response body, or <tt>null</tt> if no response
142 */
143 Object receiveBodyNoWait(String endpointUri);
144
145 /**
146 * Receives from the endpoint, not waiting for a response if non exists.
147 *
148 * @param endpoint the endpoint to receive from
149 * @return the returned response body, or <tt>null</tt> if no response
150 */
151 Object receiveBodyNoWait(Endpoint endpoint);
152
153 /**
154 * Receives from the endpoint, waiting until there is a response
155 *
156 * @param endpointUri the endpoint to receive from
157 * @param type the expected response type
158 * @return the returned response body
159 */
160 <T> T receiveBody(String endpointUri, Class<T> type);
161
162 /**
163 * Receives from the endpoint, waiting until there is a response
164 *
165 * @param endpoint the endpoint to receive from
166 * @param type the expected response type
167 * @return the returned response body
168 */
169 <T> T receiveBody(Endpoint endpoint, Class<T> type);
170
171 /**
172 * Receives from the endpoint, waiting until there is a response
173 * or the timeout occurs
174 *
175 * @param endpointUri the endpoint to receive from
176 * @param timeout timeout in millis to wait for a response
177 * @param type the expected response type
178 * @return the returned response body, or <tt>null</tt> if no response
179 */
180 <T> T receiveBody(String endpointUri, long timeout, Class<T> type);
181
182 /**
183 * Receives from the endpoint, waiting until there is a response
184 * or the timeout occurs
185 *
186 * @param endpoint the endpoint to receive from
187 * @param timeout timeout in millis to wait for a response
188 * @param type the expected response type
189 * @return the returned response body, or <tt>null</tt> if no response
190 */
191 <T> T receiveBody(Endpoint endpoint, long timeout, Class<T> type);
192
193 /**
194 * Receives from the endpoint, not waiting for a response if non exists.
195 *
196 * @param endpointUri the endpoint to receive from
197 * @param type the expected response type
198 * @return the returned response body, or <tt>null</tt> if no response
199 */
200 <T> T receiveBodyNoWait(String endpointUri, Class<T> type);
201
202 /**
203 * Receives from the endpoint, not waiting for a response if non exists.
204 *
205 * @param endpoint the endpoint to receive from
206 * @param type the expected response type
207 * @return the returned response body, or <tt>null</tt> if no response
208 */
209 <T> T receiveBodyNoWait(Endpoint endpoint, Class<T> type);
210
211 }