All Downloads are FREE. Search and download functionalities are using the official Maven repository.

org.springframework.web.client.RestOperations Maven / Gradle / Ivy

/*
 * Copyright 2002-2010 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
 *
 *      http://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 org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;

/**
 * Interface specifying a basic set of RESTful operations. Implemented by {@link RestTemplate}.
 * Not often used directly, but a useful option to enhance testability, as it can easily
 * be mocked or stubbed.
 *
 * @author Arjen Poutsma
 * @author Juergen Hoeller
 * @since 1.0
 * @see RestTemplate
 */
public interface RestOperations {

	// GET

	/**
	 * Retrieve a representation by doing a GET on the specified URL.
	 * The response (if any) is converted and returned.
	 * 

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 getForObject(String url, Class responseType, Object... uriVariables) throws RestClientException; /** * Retrieve a representation by doing a GET on the URI template. * The response (if any) is converted and returned. *

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 getForObject(String url, Class responseType, Map 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 getForObject(URI url, Class responseType) throws RestClientException; /** * 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 */ ResponseEntity getForEntity(String url, Class 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}. *

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 */ ResponseEntity getForEntity(String url, Class responseType, Map 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 */ ResponseEntity getForEntity(URI url, Class responseType) throws RestClientException; // HEAD /** * 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 */ HttpHeaders headForHeaders(String url, Object... uriVariables) throws RestClientException; /** * 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 */ HttpHeaders headForHeaders(String url, Map uriVariables) throws RestClientException; /** * Retrieve all headers of the resource specified by the URL. * @param url the URL * @return all HTTP headers of that resource */ 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 * Location header. This header typically indicates where the new resource is stored. *

URI Template variables are expanded using the given URI variables, if any. *

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 null * @param uriVariables the variables to expand the template * @return the value for the Location header * @see HttpEntity */ 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 * Location header. This header typically indicates where the new resource is stored. *

URI Template variables are expanded using the given map. *

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 null * @param uriVariables the variables to expand the template * @return the value for the Location header * @see HttpEntity */ URI postForLocation(String url, Object request, Map uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URL, and returns the value of the * Location header. This header typically indicates where the new resource is stored. *

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 null * @return the value for the Location header * @see HttpEntity */ 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. *

URI Template variables are expanded using the given URI variables, if any. *

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 null * @param responseType the type of the return value * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity */ T postForObject(String url, Object request, Class 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. *

URI Template variables are expanded using the given map. *

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 null * @param responseType the type of the return value * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity */ T postForObject(String url, Object request, Class responseType, Map uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URL, * and returns the representation found in the response. *

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 null * @param responseType the type of the return value * @return the converted object * @see HttpEntity */ T postForObject(URI url, Object request, Class responseType) throws RestClientException; /** * Create a new resource by POSTing the given object to the URI template, * and returns the response as {@link ResponseEntity}. *

URI Template variables are expanded using the given URI variables, if any. *

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 null * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity */ ResponseEntity postForEntity(String url, Object request, Class 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}. *

URI Template variables are expanded using the given map. *

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 null * @param uriVariables the variables to expand the template * @return the converted object * @see HttpEntity */ ResponseEntity postForEntity(String url, Object request, Class responseType, Map uriVariables) throws RestClientException; /** * Create a new resource by POSTing the given object to the URL, * and returns the response as {@link ResponseEntity}. *

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 null * @return the converted object * @see HttpEntity */ ResponseEntity postForEntity(URI url, Object 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 {@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 null * @param uriVariables the variables to expand the template * @see HttpEntity */ void put(String url, Object 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 {@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 null * @param uriVariables the variables to expand the template * @see HttpEntity */ void put(String url, Object request, Map uriVariables) throws RestClientException; /** * Creates a new resource by PUTting the given object to URL. *

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 null * @see HttpEntity */ void put(URI url, Object request) throws RestClientException; // DELETE /** * Delete the resources at the specified 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 */ void delete(String url, Object... uriVariables) throws RestClientException; /** * Delete the resources at the specified URI. *

URI Template variables are expanded using the given map. * * @param url the URL * @param uriVariables the variables to expand the template */ void delete(String url, Map uriVariables) throws RestClientException; /** * Delete the resources at the specified URL. * @param url the URL */ void delete(URI url) throws RestClientException; // OPTIONS /** * 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 */ Set optionsForAllow(String url, Object... uriVariables) throws RestClientException; /** * 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 */ Set optionsForAllow(String url, Map 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 */ Set 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}. *

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 */ ResponseEntity exchange(String url, HttpMethod method, HttpEntity requestEntity, Class 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}. *

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 */ ResponseEntity exchange(String url, HttpMethod method, HttpEntity requestEntity, Class responseType, Map 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 */ ResponseEntity exchange(URI url, HttpMethod method, HttpEntity requestEntity, Class 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}. *

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 execute(String url, HttpMethod method, RequestCallback requestCallback, ResponseExtractor 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}. *

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 execute(String url, HttpMethod method, RequestCallback requestCallback, ResponseExtractor responseExtractor, Map 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 execute(URI url, HttpMethod method, RequestCallback requestCallback, ResponseExtractor responseExtractor) throws RestClientException; }





© 2015 - 2024 Weber Informatics LLC | Privacy Policy