001/* 002 * Copyright 2002-2019 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; 022 023import org.springframework.core.ParameterizedTypeReference; 024import org.springframework.http.HttpEntity; 025import org.springframework.http.HttpHeaders; 026import org.springframework.http.HttpMethod; 027import org.springframework.http.RequestEntity; 028import org.springframework.http.ResponseEntity; 029import org.springframework.lang.Nullable; 030 031/** 032 * Interface specifying a basic set of RESTful operations. 033 * Implemented by {@link RestTemplate}. Not often used directly, but a useful 034 * option to enhance testability, as it can easily be mocked or stubbed. 035 * 036 * @author Arjen Poutsma 037 * @author Juergen Hoeller 038 * @since 3.0 039 * @see RestTemplate 040 */ 041public interface RestOperations { 042 043 // GET 044 045 /** 046 * Retrieve a representation by doing a GET on the specified URL. 047 * The response (if any) is converted and returned. 048 * <p>URI Template variables are expanded using the given URI variables, if any. 049 * @param url the URL 050 * @param responseType the type of the return value 051 * @param uriVariables the variables to expand the template 052 * @return the converted object 053 */ 054 @Nullable 055 <T> T getForObject(String url, Class<T> responseType, Object... uriVariables) throws RestClientException; 056 057 /** 058 * Retrieve a representation by doing a GET on the URI template. 059 * The response (if any) is converted and returned. 060 * <p>URI Template variables are expanded using the given map. 061 * @param url the URL 062 * @param responseType the type of the return value 063 * @param uriVariables the map containing variables for the URI template 064 * @return the converted object 065 */ 066 @Nullable 067 <T> T getForObject(String url, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; 068 069 /** 070 * Retrieve a representation by doing a GET on the URL . 071 * The response (if any) is converted and returned. 072 * @param url the URL 073 * @param responseType the type of the return value 074 * @return the converted object 075 */ 076 @Nullable 077 <T> T getForObject(URI url, Class<T> responseType) throws RestClientException; 078 079 /** 080 * Retrieve an entity by doing a GET on the specified URL. 081 * The response is converted and stored in an {@link ResponseEntity}. 082 * <p>URI Template variables are expanded using the given URI variables, if any. 083 * @param url the URL 084 * @param responseType the type of the return value 085 * @param uriVariables the variables to expand the template 086 * @return the entity 087 * @since 3.0.2 088 */ 089 <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Object... uriVariables) 090 throws RestClientException; 091 092 /** 093 * Retrieve a representation by doing a GET on the URI template. 094 * The response is converted and stored in an {@link ResponseEntity}. 095 * <p>URI Template variables are expanded using the given map. 096 * @param url the URL 097 * @param responseType the type of the return value 098 * @param uriVariables the map containing variables for the URI template 099 * @return the converted object 100 * @since 3.0.2 101 */ 102 <T> ResponseEntity<T> getForEntity(String url, Class<T> responseType, Map<String, ?> uriVariables) 103 throws RestClientException; 104 105 /** 106 * Retrieve a representation by doing a GET on the URL . 107 * The response is converted and stored in an {@link ResponseEntity}. 108 * @param url the URL 109 * @param responseType the type of the return value 110 * @return the converted object 111 * @since 3.0.2 112 */ 113 <T> ResponseEntity<T> getForEntity(URI url, Class<T> responseType) throws RestClientException; 114 115 116 // HEAD 117 118 /** 119 * Retrieve all headers of the resource specified by the URI template. 120 * <p>URI Template variables are expanded using the given URI variables, if any. 121 * @param url the URL 122 * @param uriVariables the variables to expand the template 123 * @return all HTTP headers of that resource 124 */ 125 HttpHeaders headForHeaders(String url, Object... uriVariables) throws RestClientException; 126 127 /** 128 * Retrieve all headers of the resource specified by the URI template. 129 * <p>URI Template variables are expanded using the given map. 130 * @param url the URL 131 * @param uriVariables the map containing variables for the URI template 132 * @return all HTTP headers of that resource 133 */ 134 HttpHeaders headForHeaders(String url, Map<String, ?> uriVariables) throws RestClientException; 135 136 /** 137 * Retrieve all headers of the resource specified by the URL. 138 * @param url the URL 139 * @return all HTTP headers of that resource 140 */ 141 HttpHeaders headForHeaders(URI url) throws RestClientException; 142 143 144 // POST 145 146 /** 147 * Create a new resource by POSTing the given object to the URI template, and returns the value of 148 * the {@code Location} header. This header typically indicates where the new resource is stored. 149 * <p>URI Template variables are expanded using the given URI variables, if any. 150 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 151 * add additional HTTP headers to the request. 152 * <p>The body of the entity, or {@code request} itself, can be a 153 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 154 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 155 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 156 * and headers. 157 * @param url the URL 158 * @param request the Object to be POSTed (may be {@code null}) 159 * @param uriVariables the variables to expand the template 160 * @return the value for the {@code Location} header 161 * @see HttpEntity 162 */ 163 @Nullable 164 URI postForLocation(String url, @Nullable Object request, Object... uriVariables) throws RestClientException; 165 166 /** 167 * Create a new resource by POSTing the given object to the URI template, and returns the value of 168 * the {@code Location} header. This header typically indicates where the new resource is stored. 169 * <p>URI Template variables are expanded using the given map. 170 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 171 * add additional HTTP headers to the request 172 * <p>The body of the entity, or {@code request} itself, can be a 173 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 174 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 175 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 176 * and headers. 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 value for the {@code Location} header 181 * @see HttpEntity 182 */ 183 @Nullable 184 URI postForLocation(String url, @Nullable Object request, Map<String, ?> uriVariables) 185 throws RestClientException; 186 187 /** 188 * Create a new resource by POSTing the given object to the URL, and returns the value of the 189 * {@code Location} header. This header typically indicates where the new resource is stored. 190 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 191 * add additional HTTP headers to the request. 192 * <p>The body of the entity, or {@code request} itself, can be a 193 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 194 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 195 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 196 * and headers. 197 * @param url the URL 198 * @param request the Object to be POSTed (may be {@code null}) 199 * @return the value for the {@code Location} header 200 * @see HttpEntity 201 */ 202 @Nullable 203 URI postForLocation(URI url, @Nullable Object request) throws RestClientException; 204 205 /** 206 * Create a new resource by POSTing the given object to the URI template, 207 * and returns the representation found in the response. 208 * <p>URI Template variables are expanded using the given URI variables, if any. 209 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 210 * add additional HTTP headers to the request. 211 * <p>The body of the entity, or {@code request} itself, can be a 212 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 213 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 214 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 215 * and headers. 216 * @param url the URL 217 * @param request the Object to be POSTed (may be {@code null}) 218 * @param responseType the type of the return value 219 * @param uriVariables the variables to expand the template 220 * @return the converted object 221 * @see HttpEntity 222 */ 223 @Nullable 224 <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, 225 Object... uriVariables) throws RestClientException; 226 227 /** 228 * Create a new resource by POSTing the given object to the URI template, 229 * and returns the representation found in the response. 230 * <p>URI Template variables are expanded using the given map. 231 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 232 * add additional HTTP headers to the request. 233 * <p>The body of the entity, or {@code request} itself, can be a 234 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 235 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 236 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 237 * and headers. 238 * @param url the URL 239 * @param request the Object to be POSTed (may be {@code null}) 240 * @param responseType the type of the return value 241 * @param uriVariables the variables to expand the template 242 * @return the converted object 243 * @see HttpEntity 244 */ 245 @Nullable 246 <T> T postForObject(String url, @Nullable Object request, Class<T> responseType, 247 Map<String, ?> uriVariables) throws RestClientException; 248 249 /** 250 * Create a new resource by POSTing the given object to the URL, 251 * and returns the representation found in the response. 252 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 253 * add additional HTTP headers to the request. 254 * <p>The body of the entity, or {@code request} itself, can be a 255 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 256 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 257 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 258 * and headers. 259 * @param url the URL 260 * @param request the Object to be POSTed (may be {@code null}) 261 * @param responseType the type of the return value 262 * @return the converted object 263 * @see HttpEntity 264 */ 265 @Nullable 266 <T> T postForObject(URI url, @Nullable Object request, Class<T> responseType) throws RestClientException; 267 268 /** 269 * Create a new resource by POSTing the given object to the URI template, 270 * and returns the response as {@link ResponseEntity}. 271 * <p>URI Template variables are expanded using the given URI variables, if any. 272 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 273 * add additional HTTP headers to the request. 274 * <p>The body of the entity, or {@code request} itself, can be a 275 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 276 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 277 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 278 * and headers. 279 * @param url the URL 280 * @param request the Object to be POSTed (may be {@code null}) 281 * @param uriVariables the variables to expand the template 282 * @return the converted object 283 * @since 3.0.2 284 * @see HttpEntity 285 */ 286 <T> ResponseEntity<T> postForEntity(String url, @Nullable Object request, Class<T> responseType, 287 Object... uriVariables) throws RestClientException; 288 289 /** 290 * Create a new resource by POSTing the given object to the URI template, 291 * and returns the response as {@link HttpEntity}. 292 * <p>URI Template variables are expanded using the given map. 293 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 294 * add additional HTTP headers to the request. 295 * <p>The body of the entity, or {@code request} itself, can be a 296 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 297 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 298 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 299 * and headers. 300 * @param url the URL 301 * @param request the Object to be POSTed (may be {@code null}) 302 * @param uriVariables the variables to expand the template 303 * @return the converted object 304 * @since 3.0.2 305 * @see HttpEntity 306 */ 307 <T> ResponseEntity<T> postForEntity(String url, @Nullable Object request, Class<T> responseType, 308 Map<String, ?> uriVariables) throws RestClientException; 309 310 /** 311 * Create a new resource by POSTing the given object to the URL, 312 * and returns the response as {@link ResponseEntity}. 313 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 314 * add additional HTTP headers to the request. 315 * <p>The body of the entity, or {@code request} itself, can be a 316 * {@link org.springframework.util.MultiValueMap MultiValueMap} to create a multipart request. 317 * The values in the {@code MultiValueMap} can be any Object representing the body of the part, 318 * or an {@link org.springframework.http.HttpEntity HttpEntity} representing a part with body 319 * and headers. 320 * @param url the URL 321 * @param request the Object to be POSTed (may be {@code null}) 322 * @return the converted object 323 * @since 3.0.2 324 * @see HttpEntity 325 */ 326 <T> ResponseEntity<T> postForEntity(URI url, @Nullable Object request, Class<T> responseType) 327 throws RestClientException; 328 329 330 // PUT 331 332 /** 333 * Create or update a resource by PUTting the given object to the URI. 334 * <p>URI Template variables are expanded using the given URI variables, if any. 335 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 336 * add additional HTTP headers to the request. 337 * @param url the URL 338 * @param request the Object to be PUT (may be {@code null}) 339 * @param uriVariables the variables to expand the template 340 * @see HttpEntity 341 */ 342 void put(String url, @Nullable Object request, Object... uriVariables) throws RestClientException; 343 344 /** 345 * Creates a new resource by PUTting the given object to URI template. 346 * <p>URI Template variables are expanded using the given map. 347 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 348 * add additional HTTP headers to the request. 349 * @param url the URL 350 * @param request the Object to be PUT (may be {@code null}) 351 * @param uriVariables the variables to expand the template 352 * @see HttpEntity 353 */ 354 void put(String url, @Nullable Object request, Map<String, ?> uriVariables) throws RestClientException; 355 356 /** 357 * Creates a new resource by PUTting the given object to URL. 358 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 359 * add additional HTTP headers to the request. 360 * @param url the URL 361 * @param request the Object to be PUT (may be {@code null}) 362 * @see HttpEntity 363 */ 364 void put(URI url, @Nullable Object request) throws RestClientException; 365 366 367 // PATCH 368 369 /** 370 * Update a resource by PATCHing the given object to the URI template, 371 * and return the representation found in the response. 372 * <p>URI Template variables are expanded using the given URI variables, if any. 373 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 374 * add additional HTTP headers to the request. 375 * <p><b>NOTE: The standard JDK HTTP library does not support HTTP PATCH. 376 * You need to use the Apache HttpComponents or OkHttp request factory.</b> 377 * @param url the URL 378 * @param request the object to be PATCHed (may be {@code null}) 379 * @param responseType the type of the return value 380 * @param uriVariables the variables to expand the template 381 * @return the converted object 382 * @since 4.3.5 383 * @see HttpEntity 384 * @see RestTemplate#setRequestFactory 385 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory 386 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory 387 */ 388 @Nullable 389 <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType, Object... uriVariables) 390 throws RestClientException; 391 392 /** 393 * Update a resource by PATCHing the given object to the URI template, 394 * and return the representation found in the response. 395 * <p>URI Template variables are expanded using the given map. 396 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 397 * add additional HTTP headers to the request. 398 * <p><b>NOTE: The standard JDK HTTP library does not support HTTP PATCH. 399 * You need to use the Apache HttpComponents or OkHttp request factory.</b> 400 * @param url the URL 401 * @param request the object to be PATCHed (may be {@code null}) 402 * @param responseType the type of the return value 403 * @param uriVariables the variables to expand the template 404 * @return the converted object 405 * @since 4.3.5 406 * @see HttpEntity 407 * @see RestTemplate#setRequestFactory 408 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory 409 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory 410 */ 411 @Nullable 412 <T> T patchForObject(String url, @Nullable Object request, Class<T> responseType, 413 Map<String, ?> uriVariables) throws RestClientException; 414 415 /** 416 * Update a resource by PATCHing the given object to the URL, 417 * and return the representation found in the response. 418 * <p>The {@code request} parameter can be a {@link HttpEntity} in order to 419 * add additional HTTP headers to the request. 420 * <p><b>NOTE: The standard JDK HTTP library does not support HTTP PATCH. 421 * You need to use the Apache HttpComponents or OkHttp request factory.</b> 422 * @param url the URL 423 * @param request the object to be PATCHed (may be {@code null}) 424 * @param responseType the type of the return value 425 * @return the converted object 426 * @since 4.3.5 427 * @see HttpEntity 428 * @see RestTemplate#setRequestFactory 429 * @see org.springframework.http.client.HttpComponentsAsyncClientHttpRequestFactory 430 * @see org.springframework.http.client.OkHttp3ClientHttpRequestFactory 431 */ 432 @Nullable 433 <T> T patchForObject(URI url, @Nullable Object request, Class<T> responseType) 434 throws RestClientException; 435 436 437 438 // DELETE 439 440 /** 441 * Delete the resources at the specified URI. 442 * <p>URI Template variables are expanded using the given URI variables, if any. 443 * @param url the URL 444 * @param uriVariables the variables to expand in the template 445 */ 446 void delete(String url, Object... uriVariables) throws RestClientException; 447 448 /** 449 * Delete the resources at the specified URI. 450 * <p>URI Template variables are expanded using the given map. 451 * 452 * @param url the URL 453 * @param uriVariables the variables to expand the template 454 */ 455 void delete(String url, Map<String, ?> uriVariables) throws RestClientException; 456 457 /** 458 * Delete the resources at the specified URL. 459 * @param url the URL 460 */ 461 void delete(URI url) throws RestClientException; 462 463 464 // OPTIONS 465 466 /** 467 * Return the value of the Allow header for the given URI. 468 * <p>URI Template variables are expanded using the given URI variables, if any. 469 * @param url the URL 470 * @param uriVariables the variables to expand in the template 471 * @return the value of the allow header 472 */ 473 Set<HttpMethod> optionsForAllow(String url, Object... uriVariables) throws RestClientException; 474 475 /** 476 * Return the value of the Allow header for the given URI. 477 * <p>URI Template variables are expanded using the given map. 478 * @param url the URL 479 * @param uriVariables the variables to expand in the template 480 * @return the value of the allow header 481 */ 482 Set<HttpMethod> optionsForAllow(String url, Map<String, ?> uriVariables) throws RestClientException; 483 484 /** 485 * Return the value of the Allow header for the given URL. 486 * @param url the URL 487 * @return the value of the allow header 488 */ 489 Set<HttpMethod> optionsForAllow(URI url) throws RestClientException; 490 491 492 // exchange 493 494 /** 495 * Execute the HTTP method to the given URI template, writing the given request entity to the request, and 496 * returns the response as {@link ResponseEntity}. 497 * <p>URI Template variables are expanded using the given URI variables, if any. 498 * @param url the URL 499 * @param method the HTTP method (GET, POST, etc) 500 * @param requestEntity the entity (headers and/or body) to write to the request 501 * may be {@code null}) 502 * @param responseType the type of the return value 503 * @param uriVariables the variables to expand in the template 504 * @return the response as entity 505 * @since 3.0.2 506 */ 507 <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, 508 Class<T> responseType, Object... uriVariables) throws RestClientException; 509 510 /** 511 * Execute the HTTP method to the given URI template, writing the given request entity to the request, and 512 * returns the response as {@link ResponseEntity}. 513 * <p>URI Template variables are expanded using the given URI variables, if any. 514 * @param url the URL 515 * @param method the HTTP method (GET, POST, etc) 516 * @param requestEntity the entity (headers and/or body) to write to the request 517 * (may be {@code null}) 518 * @param responseType the type of the return value 519 * @param uriVariables the variables to expand in the template 520 * @return the response as entity 521 * @since 3.0.2 522 */ 523 <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, 524 Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; 525 526 /** 527 * Execute the HTTP method to the given URI template, writing the given request entity to the request, and 528 * returns the response as {@link ResponseEntity}. 529 * @param url the URL 530 * @param method the HTTP method (GET, POST, etc) 531 * @param requestEntity the entity (headers and/or body) to write to the request 532 * (may be {@code null}) 533 * @param responseType the type of the return value 534 * @return the response as entity 535 * @since 3.0.2 536 */ 537 <T> ResponseEntity<T> exchange(URI url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, 538 Class<T> responseType) throws RestClientException; 539 540 /** 541 * Execute the HTTP method to the given URI template, writing the given 542 * request entity to the request, and returns the response as {@link ResponseEntity}. 543 * The given {@link ParameterizedTypeReference} is used to pass generic type information: 544 * <pre class="code"> 545 * ParameterizedTypeReference<List<MyBean>> myBean = 546 * new ParameterizedTypeReference<List<MyBean>>() {}; 547 * 548 * ResponseEntity<List<MyBean>> response = 549 * template.exchange("https://example.com",HttpMethod.GET, null, myBean); 550 * </pre> 551 * @param url the URL 552 * @param method the HTTP method (GET, POST, etc) 553 * @param requestEntity the entity (headers and/or body) to write to the 554 * request (may be {@code null}) 555 * @param responseType the type of the return value 556 * @param uriVariables the variables to expand in the template 557 * @return the response as entity 558 * @since 3.2 559 */ 560 <T> ResponseEntity<T> exchange(String url,HttpMethod method, @Nullable HttpEntity<?> requestEntity, 561 ParameterizedTypeReference<T> responseType, Object... uriVariables) throws RestClientException; 562 563 /** 564 * Execute the HTTP method to the given URI template, writing the given 565 * request entity to the request, and returns the response as {@link ResponseEntity}. 566 * The given {@link ParameterizedTypeReference} is used to pass generic type information: 567 * <pre class="code"> 568 * ParameterizedTypeReference<List<MyBean>> myBean = 569 * new ParameterizedTypeReference<List<MyBean>>() {}; 570 * 571 * ResponseEntity<List<MyBean>> response = 572 * template.exchange("https://example.com",HttpMethod.GET, null, myBean); 573 * </pre> 574 * @param url the URL 575 * @param method the HTTP method (GET, POST, etc) 576 * @param requestEntity the entity (headers and/or body) to write to the request 577 * (may be {@code null}) 578 * @param responseType the type of the return value 579 * @param uriVariables the variables to expand in the template 580 * @return the response as entity 581 * @since 3.2 582 */ 583 <T> ResponseEntity<T> exchange(String url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, 584 ParameterizedTypeReference<T> responseType, Map<String, ?> uriVariables) throws RestClientException; 585 586 /** 587 * Execute the HTTP method to the given URI template, writing the given 588 * request entity to the request, and returns the response as {@link ResponseEntity}. 589 * The given {@link ParameterizedTypeReference} is used to pass generic type information: 590 * <pre class="code"> 591 * ParameterizedTypeReference<List<MyBean>> myBean = 592 * new ParameterizedTypeReference<List<MyBean>>() {}; 593 * 594 * ResponseEntity<List<MyBean>> response = 595 * template.exchange("https://example.com",HttpMethod.GET, null, myBean); 596 * </pre> 597 * @param url the URL 598 * @param method the HTTP method (GET, POST, etc) 599 * @param requestEntity the entity (headers and/or body) to write to the request 600 * (may be {@code null}) 601 * @param responseType the type of the return value 602 * @return the response as entity 603 * @since 3.2 604 */ 605 <T> ResponseEntity<T> exchange(URI url, HttpMethod method, @Nullable HttpEntity<?> requestEntity, 606 ParameterizedTypeReference<T> responseType) throws RestClientException; 607 608 /** 609 * Execute the request specified in the given {@link RequestEntity} and return 610 * the response as {@link ResponseEntity}. Typically used in combination 611 * with the static builder methods on {@code RequestEntity}, for instance: 612 * <pre class="code"> 613 * MyRequest body = ... 614 * RequestEntity request = RequestEntity 615 * .post(new URI("https://example.com/foo")) 616 * .accept(MediaType.APPLICATION_JSON) 617 * .body(body); 618 * ResponseEntity<MyResponse> response = template.exchange(request, MyResponse.class); 619 * </pre> 620 * @param requestEntity the entity to write to the request 621 * @param responseType the type of the return value 622 * @return the response as entity 623 * @since 4.1 624 */ 625 <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, Class<T> responseType) 626 throws RestClientException; 627 628 /** 629 * Execute the request specified in the given {@link RequestEntity} and return 630 * the response as {@link ResponseEntity}. The given 631 * {@link ParameterizedTypeReference} is used to pass generic type information: 632 * <pre class="code"> 633 * MyRequest body = ... 634 * RequestEntity request = RequestEntity 635 * .post(new URI("https://example.com/foo")) 636 * .accept(MediaType.APPLICATION_JSON) 637 * .body(body); 638 * ParameterizedTypeReference<List<MyResponse>> myBean = 639 * new ParameterizedTypeReference<List<MyResponse>>() {}; 640 * ResponseEntity<List<MyResponse>> response = template.exchange(request, myBean); 641 * </pre> 642 * @param requestEntity the entity to write to the request 643 * @param responseType the type of the return value 644 * @return the response as entity 645 * @since 4.1 646 */ 647 <T> ResponseEntity<T> exchange(RequestEntity<?> requestEntity, ParameterizedTypeReference<T> responseType) 648 throws RestClientException; 649 650 651 // General execution 652 653 /** 654 * Execute the HTTP method to the given URI template, preparing the request with the 655 * {@link RequestCallback}, and reading the response with a {@link ResponseExtractor}. 656 * <p>URI Template variables are expanded using the given URI variables, if any. 657 * @param url the URL 658 * @param method the HTTP method (GET, POST, etc) 659 * @param requestCallback object that prepares the request 660 * @param responseExtractor object that extracts the return value from the response 661 * @param uriVariables the variables to expand in the template 662 * @return an arbitrary object, as returned by the {@link ResponseExtractor} 663 */ 664 @Nullable 665 <T> T execute(String url, HttpMethod method, @Nullable RequestCallback requestCallback, 666 @Nullable ResponseExtractor<T> responseExtractor, Object... uriVariables) 667 throws RestClientException; 668 669 /** 670 * Execute the HTTP method to the given URI template, preparing the request with the 671 * {@link RequestCallback}, and reading the response with a {@link ResponseExtractor}. 672 * <p>URI Template variables are expanded using the given URI variables map. 673 * @param url the URL 674 * @param method the HTTP method (GET, POST, etc) 675 * @param requestCallback object that prepares the request 676 * @param responseExtractor object that extracts the return value from the response 677 * @param uriVariables the variables to expand in the template 678 * @return an arbitrary object, as returned by the {@link ResponseExtractor} 679 */ 680 @Nullable 681 <T> T execute(String url, HttpMethod method, @Nullable RequestCallback requestCallback, 682 @Nullable ResponseExtractor<T> responseExtractor, Map<String, ?> uriVariables) 683 throws RestClientException; 684 685 /** 686 * Execute the HTTP method to the given URL, preparing the request with the 687 * {@link RequestCallback}, and reading the response with a {@link ResponseExtractor}. 688 * @param url the URL 689 * @param method the HTTP method (GET, POST, etc) 690 * @param requestCallback object that prepares the request 691 * @param responseExtractor object that extracts the return value from the response 692 * @return an arbitrary object, as returned by the {@link ResponseExtractor} 693 */ 694 @Nullable 695 <T> T execute(URI url, HttpMethod method, @Nullable RequestCallback requestCallback, 696 @Nullable ResponseExtractor<T> responseExtractor) throws RestClientException; 697 698}