package org.springframework.async.web.client; import java.net.URI; import java.util.Map; import java.util.Set; import org.springframework.async.Promise; import org.springframework.http.HttpEntity; import org.springframework.http.HttpHeaders; import org.springframework.http.HttpMethod; import org.springframework.http.ResponseEntity; import org.springframework.web.client.RestClientException; /** * @author Jon Brisbin <jon@jbrisbin.com> */ public interface AsyncRestOperations { // GET /** * Retrieve a representation by doing a GET on the specified URL. * The response (if any) is converted and returned. * <p>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 converted object */ <T> Promise<T> getForObject(String url, Class<T> responseType, Object... uriVariables) throws RestClientException; /** * Retrieve a representation by doing a GET on the URI template. * The response (if any) is converted and returned. * <p>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 converted object */ <T> Promise<T> getForObject(String url, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; /** * Retrieve a representation by doing a GET on the URL . * The response (if any) is converted and returned. * * @param url the URL * @param responseType the type of the return value * @return the converted object */ <T> Promise<T> getForObject(URI url, Class<T> responseType) throws RestClientException; /** * Retrieve an entity by doing a GET on the specified URL. * The response is converted and stored in an {@link ResponseEntity}. * <p>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 * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> getForEntity(String url, Class<T> responseType, Object... uriVariables) throws RestClientException; /** * Retrieve a representation by doing a GET on the URI template. * The response is converted and stored in an {@link ResponseEntity}. * <p>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 converted object * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> getForEntity(String url, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; /** * 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 converted object * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> getForEntity(URI url, Class<T> responseType) throws RestClientException; // HEAD /** * Retrieve all headers of the resource specified by the URI template. * <p>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 */ Promise<HttpHeaders> headForHeaders(String url, Object... uriVariables) throws RestClientException; /** * Retrieve all headers of the resource specified by the URI template. * <p>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 */ Promise<HttpHeaders> headForHeaders(String url, Map<String, ?> uriVariables) throws RestClientException; /** * Retrieve all headers of the resource specified by the URL. * * @param url the URL * @return all HTTP headers of that resource */ Promise<HttpHeaders> headForHeaders(URI url) throws RestClientException; // POST /** * Create a new resource by POSTing the given object to the URI template, and returns the value of the * <code>Location</code> header. This header typically indicates where the new resource is stored. * <p>URI Template variables are expanded using the given URI variables, if any. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param uriVariables the variables to expand the template * @return the value for the <code>Location</code> header * @see HttpEntity */ Promise<URI> postForLocation(String url, Object request, Object... uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URI template, and returns the value of the * <code>Location</code> header. This header typically indicates where the new resource is stored. * <p>URI Template variables are expanded using the given map. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param uriVariables the variables to expand the template * @return the value for the <code>Location</code> header * @see HttpEntity */ Promise<URI> postForLocation(String url, Object request, Map<String, ?> uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URL, and returns the value of the * <code>Location</code> header. This header typically indicates where the new resource is stored. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @return the value for the <code>Location</code> header * @see HttpEntity */ Promise<URI> postForLocation(URI url, Object request) throws RestClientException; /** * Create a new resource by POSTing the given object to the URI template, * and returns the representation found in the response. * <p>URI Template variables are expanded using the given URI variables, if any. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param responseType the type of the return value * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity */ <T> Promise<T> postForObject(String url, Object request, Class<T> responseType, Object... uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URI template, * and returns the representation found in the response. * <p>URI Template variables are expanded using the given map. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param responseType the type of the return value * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity */ <T> Promise<T> postForObject(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URL, * and returns the representation found in the response. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param responseType the type of the return value * @return the converted object * @see HttpEntity */ <T> Promise<T> postForObject(URI url, Object request, Class<T> responseType) throws RestClientException; /** * Create a new resource by POSTing the given object to the URI template, * and returns the response as {@link ResponseEntity}. * <p>URI Template variables are expanded using the given URI variables, if any. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> postForEntity(String url, Object request, Class<T> responseType, Object... uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URI template, * and returns the response as {@link HttpEntity}. * <p>URI Template variables are expanded using the given map. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> postForEntity(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URL, * and returns the response as {@link ResponseEntity}. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be POSTed, may be <code>null</code> * @return the converted object * @see HttpEntity * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> postForEntity(URI url, Object request, Class<T> responseType) throws RestClientException; // PUT /** * Create or update a resource by PUTting the given object to the URI. * <p>URI Template variables are expanded using the given URI variables, if any. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be PUT, may be <code>null</code> * @param uriVariables the variables to expand the template * @see HttpEntity */ Promise<Void> put(String url, Object request, Object... uriVariables) throws RestClientException; /** * Creates a new resource by PUTting the given object to URI template. * <p>URI Template variables are expanded using the given map. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be PUT, may be <code>null</code> * @param uriVariables the variables to expand the template * @see HttpEntity */ Promise<Void> put(String url, Object request, Map<String, ?> uriVariables) throws RestClientException; /** * Creates a new resource by PUTting the given object to URL. * <p>The {@code request} parameter can be a {@link HttpEntity} in order to * add additional HTTP headers to the request. * * @param url the URL * @param request the Object to be PUT, may be <code>null</code> * @see HttpEntity */ Promise<Void> put(URI url, Object request) throws RestClientException; // DELETE /** * Delete the resources at the specified URI. * <p>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 */ Promise<Void> delete(String url, Object... uriVariables) throws RestClientException; /** * Delete the resources at the specified URI. * <p>URI Template variables are expanded using the given map. * * @param url the URL * @param uriVariables the variables to expand the template */ Promise<Void> delete(String url, Map<String, ?> uriVariables) throws RestClientException; /** * Delete the resources at the specified URL. * * @param url the URL */ Promise<Void> delete(URI url) throws RestClientException; // OPTIONS /** * Return the value of the Allow header for the given URI. * <p>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 */ Promise<Set<HttpMethod>> optionsForAllow(String url, Object... uriVariables) throws RestClientException; /** * Return the value of the Allow header for the given URI. * <p>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 */ Promise<Set<HttpMethod>> optionsForAllow(String url, Map<String, ?> uriVariables) throws RestClientException; /** * Return the value of the Allow header for the given URL. * * @param url the URL * @return the value of the allow header */ Promise<Set<HttpMethod>> optionsForAllow(URI url) throws RestClientException; // exchange /** * Execute the HTTP method to the given URI template, writing the given request entity to the request, and * returns the response as {@link ResponseEntity}. * <p>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 * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> exchange(String url, HttpMethod method, HttpEntity<?> requestEntity, Class<T> responseType, Object... uriVariables) throws RestClientException; /** * Execute the HTTP method to the given URI template, writing the given request entity to the request, and * returns the response as {@link ResponseEntity}. * <p>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 * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> exchange(String url, HttpMethod method, HttpEntity<?> requestEntity, Class<T> responseType, Map<String, ?> uriVariables) throws RestClientException; /** * 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 * @since 3.0.2 */ <T> Promise<ResponseEntity<T>> exchange(URI url, HttpMethod method, HttpEntity<?> requestEntity, Class<T> responseType) throws RestClientException; // general execution /** * Execute the HTTP method to the given URI template, preparing the request with the * {@link RequestCallback}, and reading the response with a {@link ResponseExtractor}. * <p>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} */ <T> Promise<T> execute(String url, HttpMethod method, RequestCallback requestCallback, ResponseExtractor<T> responseExtractor, Object... uriVariables) throws RestClientException; /** * Execute the HTTP method to the given URI template, preparing the request with the * {@link RequestCallback}, and reading the response with a {@link ResponseExtractor}. * <p>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} */ <T> Promise<T> execute(String url, HttpMethod method, RequestCallback requestCallback, ResponseExtractor<T> responseExtractor, Map<String, ?> uriVariables) throws RestClientException; /** * Execute the HTTP method to the given URL, preparing the request with the * {@link RequestCallback}, 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} */ <T> Promise<T> execute(URI url, HttpMethod method, RequestCallback requestCallback, ResponseExtractor<T> responseExtractor) throws RestClientException; }