org.springframework.web.client.AsyncRestOperations Maven / Gradle / Ivy
/*
* Copyright 2002-2017 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.web.client;
import java.net.URI;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.Future;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.lang.Nullable;
import org.springframework.util.concurrent.ListenableFuture;
/**
* Interface specifying a basic set of asynchronous RESTful operations.
* Implemented by {@link AsyncRestTemplate}. Not often used directly, but a useful
* option to enhance testability, as it can easily be mocked or stubbed.
*
* @author Arjen Poutsma
* @since 4.0
* @see AsyncRestTemplate
* @see RestOperations
* @deprecated as of Spring 5.0, in favor of {@link org.springframework.web.reactive.function.client.WebClient}
*/
@Deprecated
public interface AsyncRestOperations {
/**
* Expose the synchronous Spring RestTemplate to allow synchronous invocation.
*/
RestOperations getRestOperations();
// GET
/**
* Asynchronously retrieve an entity by doing a GET on the specified URL.
* The response is converted and stored in an {@link ResponseEntity}.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param responseType the type of the return value
* @param uriVariables the variables to expand the template
* @return the entity wrapped in a {@link Future}
*/
ListenableFuture> getForEntity(String url, Class responseType,
Object... uriVariables) throws RestClientException;
/**
* Asynchronously retrieve a representation by doing a GET on the URI template.
* The response is converted and stored in an {@link ResponseEntity}.
* URI Template variables are expanded using the given map.
* @param url the URL
* @param responseType the type of the return value
* @param uriVariables the map containing variables for the URI template
* @return the entity wrapped in a {@link Future}
*/
ListenableFuture> getForEntity(String url, Class responseType,
Map uriVariables) throws RestClientException;
/**
* Asynchronously retrieve a representation by doing a GET on the URL.
* The response is converted and stored in an {@link ResponseEntity}.
* @param url the URL
* @param responseType the type of the return value
* @return the entity wrapped in a {@link Future}
*/
ListenableFuture> getForEntity(URI url, Class responseType)
throws RestClientException;
// HEAD
/**
* Asynchronously retrieve all headers of the resource specified by the URI template.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param uriVariables the variables to expand the template
* @return all HTTP headers of that resource wrapped in a {@link Future}
*/
ListenableFuture headForHeaders(String url, Object... uriVariables)
throws RestClientException;
/**
* Asynchronously retrieve all headers of the resource specified by the URI template.
* URI Template variables are expanded using the given map.
* @param url the URL
* @param uriVariables the map containing variables for the URI template
* @return all HTTP headers of that resource wrapped in a {@link Future}
*/
ListenableFuture headForHeaders(String url, Map uriVariables)
throws RestClientException;
/**
* Asynchronously retrieve all headers of the resource specified by the URL.
* @param url the URL
* @return all HTTP headers of that resource wrapped in a {@link Future}
*/
ListenableFuture headForHeaders(URI url) throws RestClientException;
// POST
/**
* Create a new resource by POSTing the given object to the URI template, and
* asynchronously returns the value of the {@code Location} header. This header
* typically indicates where the new resource is stored.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param request the Object to be POSTed (may be {@code null})
* @param uriVariables the variables to expand the template
* @return the value for the {@code Location} header wrapped in a {@link Future}
* @see org.springframework.http.HttpEntity
*/
ListenableFuture postForLocation(String url, @Nullable HttpEntity request, Object... uriVariables)
throws RestClientException;
/**
* Create a new resource by POSTing the given object to the URI template, and
* asynchronously returns the value of the {@code Location} header. This header
* typically indicates where the new resource is stored.
* URI Template variables are expanded using the given map.
* @param url the URL
* @param request the Object to be POSTed (may be {@code null})
* @param uriVariables the variables to expand the template
* @return the value for the {@code Location} header wrapped in a {@link Future}
* @see org.springframework.http.HttpEntity
*/
ListenableFuture postForLocation(String url, @Nullable HttpEntity request, Map uriVariables)
throws RestClientException;
/**
* Create a new resource by POSTing the given object to the URL, and asynchronously
* returns the value of the {@code Location} header. This header typically indicates
* where the new resource is stored.
* @param url the URL
* @param request the Object to be POSTed (may be {@code null})
* @return the value for the {@code Location} header wrapped in a {@link Future}
* @see org.springframework.http.HttpEntity
*/
ListenableFuture postForLocation(URI url, @Nullable HttpEntity request) throws RestClientException;
/**
* Create a new resource by POSTing the given object to the URI template,
* and asynchronously returns the response as {@link ResponseEntity}.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param request the Object to be POSTed (may be {@code null})
* @param uriVariables the variables to expand the template
* @return the entity wrapped in a {@link Future}
* @see org.springframework.http.HttpEntity
*/
ListenableFuture> postForEntity(String url, @Nullable HttpEntity request,
Class responseType, Object... uriVariables) throws RestClientException;
/**
* Create a new resource by POSTing the given object to the URI template,
* and asynchronously returns the response as {@link ResponseEntity}.
* URI Template variables are expanded using the given map.
* @param url the URL
* @param request the Object to be POSTed (may be {@code null})
* @param uriVariables the variables to expand the template
* @return the entity wrapped in a {@link Future}
* @see org.springframework.http.HttpEntity
*/
ListenableFuture> postForEntity(String url, @Nullable HttpEntity request,
Class responseType, Map uriVariables) throws RestClientException;
/**
* Create a new resource by POSTing the given object to the URL,
* and asynchronously returns the response as {@link ResponseEntity}.
* @param url the URL
* @param request the Object to be POSTed (may be {@code null})
* @return the entity wrapped in a {@link Future}
* @see org.springframework.http.HttpEntity
*/
ListenableFuture> postForEntity(URI url, @Nullable HttpEntity request,
Class responseType) throws RestClientException;
// PUT
/**
* Create or update a resource by PUTting the given object to the URI.
* URI Template variables are expanded using the given URI variables, if any.
*
The Future will return a {@code null} result upon completion.
* @param url the URL
* @param request the Object to be PUT (may be {@code null})
* @param uriVariables the variables to expand the template
* @see HttpEntity
*/
ListenableFuture put(String url, @Nullable HttpEntity request, Object... uriVariables)
throws RestClientException;
/**
* Creates a new resource by PUTting the given object to URI template.
*
URI Template variables are expanded using the given map.
*
The Future will return a {@code null} result upon completion.
* @param url the URL
* @param request the Object to be PUT (may be {@code null})
* @param uriVariables the variables to expand the template
* @see HttpEntity
*/
ListenableFuture put(String url, @Nullable HttpEntity request, Map uriVariables)
throws RestClientException;
/**
* Creates a new resource by PUTting the given object to URL.
* The Future will return a {@code null} result upon completion.
* @param url the URL
* @param request the Object to be PUT (may be {@code null})
* @see HttpEntity
*/
ListenableFuture put(URI url, @Nullable HttpEntity request) throws RestClientException;
// DELETE
/**
* Asynchronously delete the resources at the specified URI.
*
URI Template variables are expanded using the given URI variables, if any.
*
The Future will return a {@code null} result upon completion.
* @param url the URL
* @param uriVariables the variables to expand in the template
*/
ListenableFuture delete(String url, Object... uriVariables) throws RestClientException;
/**
* Asynchronously delete the resources at the specified URI.
*
URI Template variables are expanded using the given URI variables, if any.
*
The Future will return a {@code null} result upon completion.
* @param url the URL
* @param uriVariables the variables to expand in the template
*/
ListenableFuture delete(String url, Map uriVariables) throws RestClientException;
/**
* Asynchronously delete the resources at the specified URI.
* URI Template variables are expanded using the given URI variables, if any.
*
The Future will return a {@code null} result upon completion.
* @param url the URL
*/
ListenableFuture delete(URI url) throws RestClientException;
// OPTIONS
/**
* Asynchronously return the value of the Allow header for the given URI.
*
URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param uriVariables the variables to expand in the template
* @return the value of the allow header wrapped in a {@link Future}
*/
ListenableFuture> optionsForAllow(String url, Object... uriVariables)
throws RestClientException;
/**
* Asynchronously return the value of the Allow header for the given URI.
* URI Template variables are expanded using the given map.
* @param url the URL
* @param uriVariables the variables to expand in the template
* @return the value of the allow header wrapped in a {@link Future}
*/
ListenableFuture> optionsForAllow(String url, Map uriVariables)
throws RestClientException;
/**
* Asynchronously return the value of the Allow header for the given URL.
* @param url the URL
* @return the value of the allow header wrapped in a {@link Future}
*/
ListenableFuture> optionsForAllow(URI url) throws RestClientException;
// exchange
/**
* Asynchronously execute the HTTP method to the given URI template, writing the
* given request entity to the request, and returns the response as
* {@link ResponseEntity}.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestEntity the entity (headers and/or body) to write to the request
* (may be {@code null})
* @param responseType the type of the return value
* @param uriVariables the variables to expand in the template
* @return the response as entity wrapped in a {@link Future}
*/
ListenableFuture> exchange(String url, HttpMethod method,
@Nullable HttpEntity requestEntity, Class responseType, Object... uriVariables)
throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URI template, writing the
* given request entity to the request, and returns the response as
* {@link ResponseEntity}.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestEntity the entity (headers and/or body) to write to the request
* (may be {@code null})
* @param responseType the type of the return value
* @param uriVariables the variables to expand in the template
* @return the response as entity wrapped in a {@link Future}
*/
ListenableFuture> exchange(String url, HttpMethod method,
@Nullable HttpEntity requestEntity, Class responseType,
Map uriVariables) throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URI template, writing the
* given request entity to the request, and returns the response as
* {@link ResponseEntity}.
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestEntity the entity (headers and/or body) to write to the request
* (may be {@code null})
* @param responseType the type of the return value
* @return the response as entity wrapped in a {@link Future}
*/
ListenableFuture> exchange(URI url, HttpMethod method,
@Nullable HttpEntity requestEntity, Class responseType)
throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URI template, writing the given
* request entity to the request, and returns the response as {@link ResponseEntity}.
* The given {@link ParameterizedTypeReference} is used to pass generic type
* information:
*
* ParameterizedTypeReference<List<MyBean>> myBean =
* new ParameterizedTypeReference<List<MyBean>>() {};
*
* ResponseEntity<List<MyBean>> response =
* template.exchange("https://example.com",HttpMethod.GET, null, myBean);
*
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestEntity the entity (headers and/or body) to write to the
* request (may be {@code null})
* @param responseType the type of the return value
* @param uriVariables the variables to expand in the template
* @return the response as entity wrapped in a {@link Future}
*/
ListenableFuture> exchange(String url, HttpMethod method,
@Nullable HttpEntity requestEntity, ParameterizedTypeReference responseType,
Object... uriVariables) throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URI template, writing the given
* request entity to the request, and returns the response as {@link ResponseEntity}.
* The given {@link ParameterizedTypeReference} is used to pass generic type
* information:
*
* ParameterizedTypeReference<List<MyBean>> myBean =
* new ParameterizedTypeReference<List<MyBean>>() {};
*
* ResponseEntity<List<MyBean>> response =
* template.exchange("https://example.com",HttpMethod.GET, null, myBean);
*
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestEntity the entity (headers and/or body) to write to the request
* (may be {@code null})
* @param responseType the type of the return value
* @param uriVariables the variables to expand in the template
* @return the response as entity wrapped in a {@link Future}
*/
ListenableFuture> exchange(String url, HttpMethod method,
@Nullable HttpEntity requestEntity, ParameterizedTypeReference responseType,
Map uriVariables) throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URI template, writing the given
* request entity to the request, and returns the response as {@link ResponseEntity}.
* The given {@link ParameterizedTypeReference} is used to pass generic type
* information:
*
* ParameterizedTypeReference<List<MyBean>> myBean =
* new ParameterizedTypeReference<List<MyBean>>() {};
*
* ResponseEntity<List<MyBean>> response =
* template.exchange("https://example.com",HttpMethod.GET, null, myBean);
*
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestEntity the entity (headers and/or body) to write to the request
* (may be {@code null})
* @param responseType the type of the return value
* @return the response as entity wrapped in a {@link Future}
*/
ListenableFuture> exchange(URI url, HttpMethod method,
@Nullable HttpEntity requestEntity, ParameterizedTypeReference responseType)
throws RestClientException;
// general execution
/**
* Asynchronously execute the HTTP method to the given URI template, preparing the
* request with the {@link AsyncRequestCallback}, and reading the response with a
* {@link ResponseExtractor}.
* URI Template variables are expanded using the given URI variables, if any.
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestCallback object that prepares the request
* @param responseExtractor object that extracts the return value from the response
* @param uriVariables the variables to expand in the template
* @return an arbitrary object, as returned by the {@link ResponseExtractor}
*/
ListenableFuture execute(String url, HttpMethod method,
@Nullable AsyncRequestCallback requestCallback, @Nullable ResponseExtractor responseExtractor,
Object... uriVariables) throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URI template, preparing the
* request with the {@link AsyncRequestCallback}, and reading the response with a
* {@link ResponseExtractor}.
* URI Template variables are expanded using the given URI variables map.
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestCallback object that prepares the request
* @param responseExtractor object that extracts the return value from the response
* @param uriVariables the variables to expand in the template
* @return an arbitrary object, as returned by the {@link ResponseExtractor}
*/
ListenableFuture execute(String url, HttpMethod method,
@Nullable AsyncRequestCallback requestCallback, @Nullable ResponseExtractor responseExtractor,
Map uriVariables) throws RestClientException;
/**
* Asynchronously execute the HTTP method to the given URL, preparing the request
* with the {@link AsyncRequestCallback}, and reading the response with a
* {@link ResponseExtractor}.
* @param url the URL
* @param method the HTTP method (GET, POST, etc)
* @param requestCallback object that prepares the request
* @param responseExtractor object that extracts the return value from the response
* @return an arbitrary object, as returned by the {@link ResponseExtractor}
*/
ListenableFuture execute(URI url, HttpMethod method,
@Nullable AsyncRequestCallback requestCallback, @Nullable ResponseExtractor responseExtractor)
throws RestClientException;
}