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: 3131 $
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    }