RestTemplate provides patchForObject operations

Issue: SPR-14857

Author: jhoeller

spring-web/src/main/java/org/springframework/web/client/RestOperations.java

@@ -1,11 +1,11 @@
 /*
- * Copyright 2002-2014 the original author or authors.
+ * Copyright 2002-2016 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
+ *      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,
@@ -28,9 +28,9 @@
 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.
+ * 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
@@ -139,27 +139,27 @@ public interface RestOperations {
 	// POST
 
 	/**
-	 * Create a new resource by POSTing the given object to the URI template, and returns the value of the
-	 * {@code Location} header. This header typically indicates where the new resource is stored.
+	 * Create a new resource by POSTing the given object to the URI template, and returns the value of
+	 * the {@code Location} 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}
+	 * @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
 	 * @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
-	 * {@code Location} header. This header typically indicates where the new resource is stored.
+	 * Create a new resource by POSTing the given object to the URI template, and returns the value of
+	 * the {@code Location} 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}
+	 * @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
 	 * @see HttpEntity
@@ -172,7 +172,7 @@ public interface RestOperations {
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the value for the {@code Location} header
 	 * @see HttpEntity
 	 */
@@ -185,7 +185,7 @@ public interface RestOperations {
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
@@ -201,7 +201,7 @@ <T> T postForObject(String url, Object request, Class<T> responseType, Object...
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
@@ -216,7 +216,7 @@ <T> T postForObject(String url, Object request, Class<T> responseType, Map<Strin
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param responseType the type of the return value
 	 * @return the converted object
 	 * @see HttpEntity
@@ -230,11 +230,11 @@ <T> T postForObject(String url, Object request, Class<T> responseType, Map<Strin
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
-	 * @see HttpEntity
 	 * @since 3.0.2
+	 * @see HttpEntity
 	 */
 	<T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Object... uriVariables)
 			throws RestClientException;
@@ -246,11 +246,11 @@ <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> respons
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @return the converted object
-	 * @see HttpEntity
 	 * @since 3.0.2
+	 * @see HttpEntity
 	 */
 	<T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables)
 			throws RestClientException;
@@ -261,10 +261,10 @@ <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> respons
 	 * <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}
+	 * @param request the Object to be POSTed (may be {@code null})
 	 * @return the converted object
-	 * @see HttpEntity
 	 * @since 3.0.2
+	 * @see HttpEntity
 	 */
 	<T> ResponseEntity<T> postForEntity(URI url, Object request, Class<T> responseType) throws RestClientException;
 
@@ -277,7 +277,7 @@ <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> respons
 	 * <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}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @see HttpEntity
 	 */
@@ -289,7 +289,7 @@ <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> respons
 	 * <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}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @param uriVariables the variables to expand the template
 	 * @see HttpEntity
 	 */
@@ -300,12 +300,64 @@ <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> respons
 	 * <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}
+	 * @param request the Object to be PUT (may be {@code null})
 	 * @see HttpEntity
 	 */
 	void put(URI url, Object request) throws RestClientException;
 
 
+	// PATCH
+
+	/**
+	 * Update a resource by PATCHing 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 PATCHed (may be {@code null})
+	 * @param responseType the type of the return value
+	 * @param uriVariables the variables to expand the template
+	 * @return the converted object
+	 * @since 4.3.5
+	 * @see HttpEntity
+	 */
+	<T> T patchForObject(String url, Object request, Class<T> responseType, Object... uriVariables)
+			throws RestClientException;
+
+	/**
+	 * Update a resource by PATCHing 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 PATCHed (may be {@code null})
+	 * @param responseType the type of the return value
+	 * @param uriVariables the variables to expand the template
+	 * @return the converted object
+	 * @since 4.3.5
+	 * @see HttpEntity
+	 */
+	<T> T patchForObject(String url, Object request, Class<T> responseType, Map<String, ?> uriVariables)
+			throws RestClientException;
+
+	/**
+	 * Update a resource by PATCHing 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 PATCHed (may be {@code null})
+	 * @param responseType the type of the return value
+	 * @return the converted object
+	 * @since 4.3.5
+	 * @see HttpEntity
+	 */
+	<T> T patchForObject(URI url, Object request, Class<T> responseType) throws RestClientException;
+
+
+
 	// DELETE
 
 	/**
@@ -368,7 +420,8 @@ <T> ResponseEntity<T> postForEntity(String url, Object request, Class<T> respons
 	 * <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 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
@@ -383,7 +436,8 @@ <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<?> requ
 	 * <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 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
@@ -397,7 +451,8 @@ <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<?> requ
 	 * 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 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
@@ -416,7 +471,7 @@ <T> ResponseEntity<T> exchange(URI url, HttpMethod method, HttpEntity<?> request
 	 * @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}
+	 * 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
@@ -435,7 +490,8 @@ <T> ResponseEntity<T> exchange(String url,HttpMethod method, HttpEntity<?> reque
 	 * </pre>
 	 * @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 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
@@ -454,7 +510,8 @@ <T> ResponseEntity<T> exchange(String url, HttpMethod method, HttpEntity<?> requ
 	 * </pre>
 	 * @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 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.2

spring-web/src/main/java/org/springframework/web/client/RestTemplate.java

@@ -445,6 +445,39 @@ public void put(URI url, Object request) throws RestClientException {
 	}
 
 
+	// PATCH
+
+	@Override
+	public <T> T patchForObject(String url, Object request, Class<T> responseType,
+			Object... uriVariables) throws RestClientException {
+
+		RequestCallback requestCallback = httpEntityCallback(request, responseType);
+		HttpMessageConverterExtractor<T> responseExtractor =
+				new HttpMessageConverterExtractor<T>(responseType, getMessageConverters(), logger);
+		return execute(url, HttpMethod.PATCH, requestCallback, responseExtractor, uriVariables);
+	}
+
+	@Override
+	public <T> T patchForObject(String url, Object request, Class<T> responseType,
+			Map<String, ?> uriVariables) throws RestClientException {
+
+		RequestCallback requestCallback = httpEntityCallback(request, responseType);
+		HttpMessageConverterExtractor<T> responseExtractor =
+				new HttpMessageConverterExtractor<T>(responseType, getMessageConverters(), logger);
+		return execute(url, HttpMethod.PATCH, requestCallback, responseExtractor, uriVariables);
+	}
+
+	@Override
+	public <T> T patchForObject(URI url, Object request, Class<T> responseType)
+			throws RestClientException {
+
+		RequestCallback requestCallback = httpEntityCallback(request, responseType);
+		HttpMessageConverterExtractor<T> responseExtractor =
+				new HttpMessageConverterExtractor<T>(responseType, getMessageConverters());
+		return execute(url, HttpMethod.PATCH, requestCallback, responseExtractor);
+	}
+
+
 	// DELETE
 
 	@Override
@@ -647,8 +680,8 @@ protected <T> T doExecute(URI url, HttpMethod method, RequestCallback requestCal
 	 * @param method the HTTP method to execute (GET, POST, etc.)
 	 * @param response the resulting {@link ClientHttpResponse}
 	 * @throws IOException if propagated from {@link ResponseErrorHandler}
-	 * @see #setErrorHandler
 	 * @since 4.1.6
+	 * @see #setErrorHandler
 	 */
 	protected void handleResponse(URI url, HttpMethod method, ClientHttpResponse response) throws IOException {
 		ResponseErrorHandler errorHandler = getErrorHandler();

spring-web/src/test/java/org/springframework/web/client/RestTemplateIntegrationTests.java

@@ -154,6 +154,15 @@ public void postForObject() throws URISyntaxException {
 		assertEquals("Invalid content", helloWorld, s);
 	}
 
+	@Test
+	public void patchForObject() throws URISyntaxException {
+		// JDK client does not support the PATCH method
+		Assume.assumeThat(this.clientHttpRequestFactory,
+				Matchers.not(Matchers.instanceOf(SimpleClientHttpRequestFactory.class)));
+		String s = template.patchForObject(baseUrl + "/{method}", helloWorld, String.class, "patch");
+		assertEquals("Invalid content", helloWorld, s);
+	}
+
 	@Test
 	public void notFound() {
 		try {