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