001/* 002 * Copyright 2002-2017 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.web.client; 018 019import java.net.URI; 020import java.util.Map; 021import java.util.Set; 022import java.util.concurrent.Future; 023 024import org.springframework.core.ParameterizedTypeReference; 025import org.springframework.http.HttpEntity; 026import org.springframework.http.HttpHeaders; 027import org.springframework.http.HttpMethod; 028import org.springframework.http.ResponseEntity; 029import org.springframework.lang.Nullable; 030import org.springframework.util.concurrent.ListenableFuture; 031 032/** 033 * Interface specifying a basic set of asynchronous RESTful operations. 034 * Implemented by {@link AsyncRestTemplate}. Not often used directly, but a useful 035 * option to enhance testability, as it can easily be mocked or stubbed. 036 * 037 * @author Arjen Poutsma 038 * @since 4.0 039 * @see AsyncRestTemplate 040 * @see RestOperations 041 * @deprecated as of Spring 5.0, in favor of {@link org.springframework.web.reactive.function.client.WebClient} 042 */ 043@Deprecated 044public interface AsyncRestOperations { 045 046 /** 047 * Expose the synchronous Spring RestTemplate to allow synchronous invocation. 048 */ 049 RestOperations getRestOperations(); 050 051 052 // GET 053 054 /** 055 * Asynchronously retrieve an entity by doing a GET on the specified URL. 056 * The response is converted and stored in an {@link ResponseEntity}. 057 * <p>URI Template variables are expanded using the given URI variables, if any. 058 * @param url the URL 059 * @param responseType the type of the return value 060 * @param uriVariables the variables to expand the template 061 * @return the entity wrapped in a {@link Future} 062 */ 063 <T> ListenableFuture<ResponseEntity<T>> getForEntity(String url, Class<T> responseType, 064 Object... uriVariables) throws RestClientException; 065 066 /** 067 * Asynchronously retrieve a representation by doing a GET on the URI template. 068 * The response is converted and stored in an {@link ResponseEntity}. 069 * <p>URI Template variables are expanded using the given map. 070 * @param url the URL 071 * @param responseType the type of the return value 072 * @param uriVariables the map containing variables for the URI template 073 * @return the entity wrapped in a {@link Future} 074 */ 075 <T> ListenableFuture<ResponseEntity<T>> getForEntity(String url, Class<T> responseType, 076 Map<String, ?> uriVariables) throws RestClientException; 077 078 /** 079 * Asynchronously retrieve a representation by doing a GET on the URL. 080 * The response is converted and stored in an {@link ResponseEntity}. 081 * @param url the URL 082 * @param responseType the type of the return value 083 * @return the entity wrapped in a {@link Future} 084 */ 085 <T> ListenableFuture<ResponseEntity<T>> getForEntity(URI url, Class<T> responseType) 086 throws RestClientException; 087 088 089 // HEAD 090 091 /** 092 * Asynchronously retrieve all headers of the resource specified by the URI template. 093 * <p>URI Template variables are expanded using the given URI variables, if any. 094 * @param url the URL 095 * @param uriVariables the variables to expand the template 096 * @return all HTTP headers of that resource wrapped in a {@link Future} 097 */ 098 ListenableFuture<HttpHeaders> headForHeaders(String url, Object... uriVariables) 099 throws RestClientException; 100 101 /** 102 * Asynchronously retrieve all headers of the resource specified by the URI template. 103 * <p>URI Template variables are expanded using the given map. 104 * @param url the URL 105 * @param uriVariables the map containing variables for the URI template 106 * @return all HTTP headers of that resource wrapped in a {@link Future} 107 */ 108 ListenableFuture<HttpHeaders> headForHeaders(String url, Map<String, ?> uriVariables) 109 throws RestClientException; 110 111 /** 112 * Asynchronously retrieve all headers of the resource specified by the URL. 113 * @param url the URL 114 * @return all HTTP headers of that resource wrapped in a {@link Future} 115 */ 116 ListenableFuture<HttpHeaders> headForHeaders(URI url) throws RestClientException; 117 118 119 // POST 120 121 /** 122 * Create a new resource by POSTing the given object to the URI template, and 123 * asynchronously returns the value of the {@code Location} header. This header 124 * typically indicates where the new resource is stored. 125 * <p>URI Template variables are expanded using the given URI variables, if any. 126 * @param url the URL 127 * @param request the Object to be POSTed (may be {@code null}) 128 * @param uriVariables the variables to expand the template 129 * @return the value for the {@code Location} header wrapped in a {@link Future} 130 * @see org.springframework.http.HttpEntity 131 */ 132 ListenableFuture<URI> postForLocation(String url, @Nullable HttpEntity<?> request, Object... uriVariables) 133 throws RestClientException; 134 135 /** 136 * Create a new resource by POSTing the given object to the URI template, and 137 * asynchronously returns the value of the {@code Location} header. This header 138 * typically indicates where the new resource is stored. 139 * <p>URI Template variables are expanded using the given map. 140 * @param url the URL 141 * @param request the Object to be POSTed (may be {@code null}) 142 * @param uriVariables the variables to expand the template 143 * @return the value for the {@code Location} header wrapped in a {@link Future} 144 * @see org.springframework.http.HttpEntity 145 */ 146 ListenableFuture<URI> postForLocation(String url, @Nullable HttpEntity<?> request, Map<String, ?> uriVariables) 147 throws RestClientException; 148 149 /** 150 * Create a new resource by POSTing the given object to the URL, and asynchronously 151 * returns the value of the {@code Location} header. This header typically indicates 152 * where the new resource is stored. 153 * @param url the URL 154 * @param request the Object to be POSTed (may be {@code null}) 155 * @return the value for the {@code Location} header wrapped in a {@link Future} 156 * @see org.springframework.http.HttpEntity 157 */ 158 ListenableFuture<URI> postForLocation(URI url, @Nullable HttpEntity<?> request) throws RestClientException; 159 160 /** 161 * Create a new resource by POSTing the given object to the URI template, 162 * and asynchronously returns the response as {@link ResponseEntity}. 163 * <p>URI Template variables are expanded using the given URI variables, if any. 164 * @param url the URL 165 * @param request the Object to be POSTed (may be {@code null}) 166 * @param uriVariables the variables to expand the template 167 * @return the entity wrapped in a {@link Future} 168 * @see org.springframework.http.HttpEntity 169 */ 170 <T> ListenableFuture<ResponseEntity<T>> postForEntity(String url, @Nullable HttpEntity<?> request, 171 Class<T> responseType, Object... uriVariables) throws RestClientException; 172 173 /** 174 * Create a new resource by POSTing the given object to the URI template, 175 * and asynchronously returns the response as {@link ResponseEntity}. 176 * <p>URI Template variables are expanded using the given map. 177 * @param url the URL 178 * @param request the Object to be POSTed (may be {@code null}) 179 * @param uriVariables the variables to expand the template 180 * @return the entity wrapped in a {@link Future} 181 * @see org.springframework.http.HttpEntity 182 */ 183 <T> ListenableFuture<ResponseEntity<T>> postForEntity(String url, @Nullable HttpEntity<?> request, 184 Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; 185 186 /** 187 * Create a new resource by POSTing the given object to the URL, 188 * and asynchronously returns the response as {@link ResponseEntity}. 189 * @param url the URL 190 * @param request the Object to be POSTed (may be {@code null}) 191 * @return the entity wrapped in a {@link Future} 192 * @see org.springframework.http.HttpEntity 193 */ 194 <T> ListenableFuture<ResponseEntity<T>> postForEntity(URI url, @Nullable HttpEntity<?> request, 195 Class<T> responseType) throws RestClientException; 196 197 198 // PUT 199 200 /** 201 * Create or update a resource by PUTting the given object to the URI. 202 * <p>URI Template variables are expanded using the given URI variables, if any. 203 * <p>The Future will return a {@code null} result upon completion. 204 * @param url the URL 205 * @param request the Object to be PUT (may be {@code null}) 206 * @param uriVariables the variables to expand the template 207 * @see HttpEntity 208 */ 209 ListenableFuture<?> put(String url, @Nullable HttpEntity<?> request, Object... uriVariables) 210 throws RestClientException; 211 212 /** 213 * Creates a new resource by PUTting the given object to URI template. 214 * <p>URI Template variables are expanded using the given map. 215 * <p>The Future will return a {@code null} result upon completion. 216 * @param url the URL 217 * @param request the Object to be PUT (may be {@code null}) 218 * @param uriVariables the variables to expand the template 219 * @see HttpEntity 220 */ 221 ListenableFuture<?> put(String url, @Nullable HttpEntity<?> request, Map<String, ?> uriVariables) 222 throws RestClientException; 223 224 /** 225 * Creates a new resource by PUTting the given object to URL. 226 * <p>The Future will return a {@code null} result upon completion. 227 * @param url the URL 228 * @param request the Object to be PUT (may be {@code null}) 229 * @see HttpEntity 230 */ 231 ListenableFuture<?> put(URI url, @Nullable HttpEntity<?> request) throws RestClientException; 232 233 234 // DELETE 235 236 /** 237 * Asynchronously delete the resources at the specified URI. 238 * <p>URI Template variables are expanded using the given URI variables, if any. 239 * <p>The Future will return a {@code null} result upon completion. 240 * @param url the URL 241 * @param uriVariables the variables to expand in the template 242 */ 243 ListenableFuture<?> delete(String url, Object... uriVariables) throws RestClientException; 244 245 /** 246 * Asynchronously delete the resources at the specified URI. 247 * <p>URI Template variables are expanded using the given URI variables, if any. 248 * <p>The Future will return a {@code null} result upon completion. 249 * @param url the URL 250 * @param uriVariables the variables to expand in the template 251 */ 252 ListenableFuture<?> delete(String url, Map<String, ?> uriVariables) throws RestClientException; 253 254 /** 255 * Asynchronously delete the resources at the specified URI. 256 * <p>URI Template variables are expanded using the given URI variables, if any. 257 * <p>The Future will return a {@code null} result upon completion. 258 * @param url the URL 259 */ 260 ListenableFuture<?> delete(URI url) throws RestClientException; 261 262 263 // OPTIONS 264 265 /** 266 * Asynchronously return the value of the Allow header for the given URI. 267 * <p>URI Template variables are expanded using the given URI variables, if any. 268 * @param url the URL 269 * @param uriVariables the variables to expand in the template 270 * @return the value of the allow header wrapped in a {@link Future} 271 */ 272 ListenableFuture<Set<HttpMethod>> optionsForAllow(String url, Object... uriVariables) 273 throws RestClientException; 274 275 /** 276 * Asynchronously return the value of the Allow header for the given URI. 277 * <p>URI Template variables are expanded using the given map. 278 * @param url the URL 279 * @param uriVariables the variables to expand in the template 280 * @return the value of the allow header wrapped in a {@link Future} 281 */ 282 ListenableFuture<Set<HttpMethod>> optionsForAllow(String url, Map<String, ?> uriVariables) 283 throws RestClientException; 284 285 /** 286 * Asynchronously return the value of the Allow header for the given URL. 287 * @param url the URL 288 * @return the value of the allow header wrapped in a {@link Future} 289 */ 290 ListenableFuture<Set<HttpMethod>> optionsForAllow(URI url) throws RestClientException; 291 292 293 // exchange 294 295 /** 296 * Asynchronously execute the HTTP method to the given URI template, writing the 297 * given request entity to the request, and returns the response as 298 * {@link ResponseEntity}. 299 * <p>URI Template variables are expanded using the given URI variables, if any. 300 * @param url the URL 301 * @param method the HTTP method (GET, POST, etc) 302 * @param requestEntity the entity (headers and/or body) to write to the request 303 * (may be {@code null}) 304 * @param responseType the type of the return value 305 * @param uriVariables the variables to expand in the template 306 * @return the response as entity wrapped in a {@link Future} 307 */ 308 <T> ListenableFuture<ResponseEntity<T>> exchange(String url, HttpMethod method, 309 @Nullable HttpEntity<?> requestEntity, Class<T> responseType, Object... uriVariables) 310 throws RestClientException; 311 312 /** 313 * Asynchronously execute the HTTP method to the given URI template, writing the 314 * given request entity to the request, and returns the response as 315 * {@link ResponseEntity}. 316 * <p>URI Template variables are expanded using the given URI variables, if any. 317 * @param url the URL 318 * @param method the HTTP method (GET, POST, etc) 319 * @param requestEntity the entity (headers and/or body) to write to the request 320 * (may be {@code null}) 321 * @param responseType the type of the return value 322 * @param uriVariables the variables to expand in the template 323 * @return the response as entity wrapped in a {@link Future} 324 */ 325 <T> ListenableFuture<ResponseEntity<T>> exchange(String url, HttpMethod method, 326 @Nullable HttpEntity<?> requestEntity, Class<T> responseType, 327 Map<String, ?> uriVariables) throws RestClientException; 328 329 /** 330 * Asynchronously execute the HTTP method to the given URI template, writing the 331 * given request entity to the request, and returns the response as 332 * {@link ResponseEntity}. 333 * @param url the URL 334 * @param method the HTTP method (GET, POST, etc) 335 * @param requestEntity the entity (headers and/or body) to write to the request 336 * (may be {@code null}) 337 * @param responseType the type of the return value 338 * @return the response as entity wrapped in a {@link Future} 339 */ 340 <T> ListenableFuture<ResponseEntity<T>> exchange(URI url, HttpMethod method, 341 @Nullable HttpEntity<?> requestEntity, Class<T> responseType) 342 throws RestClientException; 343 344 /** 345 * Asynchronously execute the HTTP method to the given URI template, writing the given 346 * request entity to the request, and returns the response as {@link ResponseEntity}. 347 * The given {@link ParameterizedTypeReference} is used to pass generic type 348 * information: 349 * <pre class="code"> 350 * ParameterizedTypeReference<List<MyBean>> myBean = 351 * new ParameterizedTypeReference<List<MyBean>>() {}; 352 * 353 * ResponseEntity<List<MyBean>> response = 354 * template.exchange("https://example.com",HttpMethod.GET, null, myBean); 355 * </pre> 356 * @param url the URL 357 * @param method the HTTP method (GET, POST, etc) 358 * @param requestEntity the entity (headers and/or body) to write to the 359 * request (may be {@code null}) 360 * @param responseType the type of the return value 361 * @param uriVariables the variables to expand in the template 362 * @return the response as entity wrapped in a {@link Future} 363 */ 364 <T> ListenableFuture<ResponseEntity<T>> exchange(String url, HttpMethod method, 365 @Nullable HttpEntity<?> requestEntity, ParameterizedTypeReference<T> responseType, 366 Object... uriVariables) throws RestClientException; 367 368 /** 369 * Asynchronously execute the HTTP method to the given URI template, writing the given 370 * request entity to the request, and returns the response as {@link ResponseEntity}. 371 * The given {@link ParameterizedTypeReference} is used to pass generic type 372 * information: 373 * <pre class="code"> 374 * ParameterizedTypeReference<List<MyBean>> myBean = 375 * new ParameterizedTypeReference<List<MyBean>>() {}; 376 * 377 * ResponseEntity<List<MyBean>> response = 378 * template.exchange("https://example.com",HttpMethod.GET, null, myBean); 379 * </pre> 380 * @param url the URL 381 * @param method the HTTP method (GET, POST, etc) 382 * @param requestEntity the entity (headers and/or body) to write to the request 383 * (may be {@code null}) 384 * @param responseType the type of the return value 385 * @param uriVariables the variables to expand in the template 386 * @return the response as entity wrapped in a {@link Future} 387 */ 388 <T> ListenableFuture<ResponseEntity<T>> exchange(String url, HttpMethod method, 389 @Nullable HttpEntity<?> requestEntity, ParameterizedTypeReference<T> responseType, 390 Map<String, ?> uriVariables) throws RestClientException; 391 392 /** 393 * Asynchronously execute the HTTP method to the given URI template, writing the given 394 * request entity to the request, and returns the response as {@link ResponseEntity}. 395 * The given {@link ParameterizedTypeReference} is used to pass generic type 396 * information: 397 * <pre class="code"> 398 * ParameterizedTypeReference<List<MyBean>> myBean = 399 * new ParameterizedTypeReference<List<MyBean>>() {}; 400 * 401 * ResponseEntity<List<MyBean>> response = 402 * template.exchange("https://example.com",HttpMethod.GET, null, myBean); 403 * </pre> 404 * @param url the URL 405 * @param method the HTTP method (GET, POST, etc) 406 * @param requestEntity the entity (headers and/or body) to write to the request 407 * (may be {@code null}) 408 * @param responseType the type of the return value 409 * @return the response as entity wrapped in a {@link Future} 410 */ 411 <T> ListenableFuture<ResponseEntity<T>> exchange(URI url, HttpMethod method, 412 @Nullable HttpEntity<?> requestEntity, ParameterizedTypeReference<T> responseType) 413 throws RestClientException; 414 415 416 // general execution 417 418 /** 419 * Asynchronously execute the HTTP method to the given URI template, preparing the 420 * request with the {@link AsyncRequestCallback}, and reading the response with a 421 * {@link ResponseExtractor}. 422 * <p>URI Template variables are expanded using the given URI variables, if any. 423 * @param url the URL 424 * @param method the HTTP method (GET, POST, etc) 425 * @param requestCallback object that prepares the request 426 * @param responseExtractor object that extracts the return value from the response 427 * @param uriVariables the variables to expand in the template 428 * @return an arbitrary object, as returned by the {@link ResponseExtractor} 429 */ 430 <T> ListenableFuture<T> execute(String url, HttpMethod method, 431 @Nullable AsyncRequestCallback requestCallback, @Nullable ResponseExtractor<T> responseExtractor, 432 Object... uriVariables) throws RestClientException; 433 434 /** 435 * Asynchronously execute the HTTP method to the given URI template, preparing the 436 * request with the {@link AsyncRequestCallback}, and reading the response with a 437 * {@link ResponseExtractor}. 438 * <p>URI Template variables are expanded using the given URI variables map. 439 * @param url the URL 440 * @param method the HTTP method (GET, POST, etc) 441 * @param requestCallback object that prepares the request 442 * @param responseExtractor object that extracts the return value from the response 443 * @param uriVariables the variables to expand in the template 444 * @return an arbitrary object, as returned by the {@link ResponseExtractor} 445 */ 446 <T> ListenableFuture<T> execute(String url, HttpMethod method, 447 @Nullable AsyncRequestCallback requestCallback, @Nullable ResponseExtractor<T> responseExtractor, 448 Map<String, ?> uriVariables) throws RestClientException; 449 450 /** 451 * Asynchronously execute the HTTP method to the given URL, preparing the request 452 * with the {@link AsyncRequestCallback}, and reading the response with a 453 * {@link ResponseExtractor}. 454 * @param url the URL 455 * @param method the HTTP method (GET, POST, etc) 456 * @param requestCallback object that prepares the request 457 * @param responseExtractor object that extracts the return value from the response 458 * @return an arbitrary object, as returned by the {@link ResponseExtractor} 459 */ 460 <T> ListenableFuture<T> execute(URI url, HttpMethod method, 461 @Nullable AsyncRequestCallback requestCallback, @Nullable ResponseExtractor<T> responseExtractor) 462 throws RestClientException; 463 464}