diff --git a/spring-oxm/src/main/java/org/springframework/oxm/Marshaller.java b/spring-oxm/src/main/java/org/springframework/oxm/Marshaller.java index 9dfb7214d2..2fe594f2e8 100644 --- a/spring-oxm/src/main/java/org/springframework/oxm/Marshaller.java +++ b/spring-oxm/src/main/java/org/springframework/oxm/Marshaller.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2012 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. @@ -35,7 +35,7 @@ import javax.xml.transform.Result; public interface Marshaller { /** - * Indicates whether this marshaller can marshal instances of the supplied type. + * Indicate whether this marshaller can marshal instances of the supplied type. * @param clazz the class that this marshaller is being asked if it can marshal * @return {@code true} if this marshaller can indeed marshal instances of the supplied class; * {@code false} otherwise @@ -43,7 +43,7 @@ public interface Marshaller { boolean supports(Class clazz); /** - * Marshals the object graph with the given root into the provided {@link Result}. + * Marshal the object graph with the given root into the provided {@link Result}. * @param graph the root of the object graph to marshal * @param result the result to marshal to * @throws IOException if an I/O error occurs diff --git a/spring-oxm/src/main/java/org/springframework/oxm/Unmarshaller.java b/spring-oxm/src/main/java/org/springframework/oxm/Unmarshaller.java index e5fbb959ad..400cc9bc5d 100644 --- a/spring-oxm/src/main/java/org/springframework/oxm/Unmarshaller.java +++ b/spring-oxm/src/main/java/org/springframework/oxm/Unmarshaller.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2012 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. @@ -30,7 +30,7 @@ import javax.xml.transform.Source; public interface Unmarshaller { /** - * Indicates whether this unmarshaller can unmarshal instances of the supplied type. + * Indicate whether this unmarshaller can unmarshal instances of the supplied type. * @param clazz the class that this unmarshaller is being asked if it can marshal * @return {@code true} if this unmarshaller can indeed unmarshal to the supplied class; * {@code false} otherwise @@ -38,7 +38,7 @@ public interface Unmarshaller { boolean supports(Class clazz); /** - * Unmarshals the given {@link Source} into an object graph. + * Unmarshal the given {@link Source} into an object graph. * @param source the source to marshal from * @return the object graph * @throws IOException if an I/O error occurs diff --git a/spring-web/src/main/java/org/springframework/web/client/AsyncRestOperations.java b/spring-web/src/main/java/org/springframework/web/client/AsyncRestOperations.java index 0c4420366e..19658f6bb6 100644 --- a/spring-web/src/main/java/org/springframework/web/client/AsyncRestOperations.java +++ b/spring-web/src/main/java/org/springframework/web/client/AsyncRestOperations.java @@ -1,5 +1,5 @@ /* - * Copyright 2002-2013 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. @@ -29,12 +29,14 @@ import org.springframework.http.ResponseEntity; 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. + * 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 */ public interface AsyncRestOperations { @@ -47,8 +49,8 @@ public interface AsyncRestOperations { // GET /** - * Asynchronously retrieve an entity by doing a GET on the specified URL. The response is - * converted and stored in an {@link ResponseEntity}. + * 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 @@ -59,8 +61,8 @@ public interface AsyncRestOperations { 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}. + * 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 @@ -80,6 +82,7 @@ public interface AsyncRestOperations { ListenableFuture> getForEntity(URI url, Class responseType) throws RestClientException; + // HEAD /** @@ -109,6 +112,7 @@ public interface AsyncRestOperations { */ ListenableFuture headForHeaders(URI url) throws RestClientException; + // POST /** @@ -117,7 +121,7 @@ public interface AsyncRestOperations { * 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 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 @@ -131,7 +135,7 @@ public interface AsyncRestOperations { * 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 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 @@ -144,7 +148,7 @@ public interface AsyncRestOperations { * 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} + * @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 */ @@ -155,7 +159,7 @@ public interface AsyncRestOperations { * 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 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 @@ -168,26 +172,26 @@ public interface AsyncRestOperations { * 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 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, HttpEntity request, - Class responseType, Map uriVariables) - throws RestClientException; + 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} + * @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, HttpEntity request, Class responseType) throws RestClientException; + // PUT /** @@ -195,7 +199,7 @@ public interface AsyncRestOperations { *

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 request the Object to be PUT (may be {@code null}) * @param uriVariables the variables to expand the template * @see HttpEntity */ @@ -207,7 +211,7 @@ public interface AsyncRestOperations { *

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 request the Object to be PUT (may be {@code null}) * @param uriVariables the variables to expand the template * @see HttpEntity */ @@ -218,11 +222,12 @@ public interface AsyncRestOperations { * 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} + * @param request the Object to be PUT (may be {@code null}) * @see HttpEntity */ ListenableFuture put(URI url, HttpEntity request) throws RestClientException; + // DELETE /** @@ -251,6 +256,7 @@ public interface AsyncRestOperations { */ ListenableFuture delete(URI url) throws RestClientException; + // OPTIONS /** @@ -344,7 +350,7 @@ public interface AsyncRestOperations { * @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 wrapped in a {@link Future} @@ -364,7 +370,8 @@ public interface AsyncRestOperations { * * @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 wrapped in a {@link Future} @@ -384,7 +391,8 @@ public interface AsyncRestOperations { * * @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 wrapped in a {@link Future} */ diff --git a/spring-web/src/main/java/org/springframework/web/client/AsyncRestTemplate.java b/spring-web/src/main/java/org/springframework/web/client/AsyncRestTemplate.java index 98bae8b9a9..351c46e7ad 100644 --- a/spring-web/src/main/java/org/springframework/web/client/AsyncRestTemplate.java +++ b/spring-web/src/main/java/org/springframework/web/client/AsyncRestTemplate.java @@ -53,10 +53,8 @@ import org.springframework.web.util.UriTemplateHandler; * wrappers as opposed to concrete results. * *

The {@code AsyncRestTemplate} exposes a synchronous {@link RestTemplate} via the - * {@link #getRestOperations()} method, and it shares its - * {@linkplain #setErrorHandler(ResponseErrorHandler) error handler} and - * {@linkplain #setMessageConverters(List) message converters} with this - * {@code RestTemplate}. + * {@link #getRestOperations()} method and shares its {@linkplain #setErrorHandler error handler} + * and {@linkplain #setMessageConverters message converters} with that {@code RestTemplate}. * *

Note: by default {@code AsyncRestTemplate} relies on * standard JDK facilities to establish HTTP connections. You can switch to use diff --git a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java index 2f453a8e74..36161c353c 100644 --- a/spring-web/src/main/java/org/springframework/web/client/RestOperations.java +++ b/spring-web/src/main/java/org/springframework/web/client/RestOperations.java @@ -28,9 +28,9 @@ import org.springframework.http.RequestEntity; 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,13 +139,13 @@ 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. *

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 {@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 @@ -153,13 +153,13 @@ public interface RestOperations { 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. *

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 {@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 { *

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 { *

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 @@ public interface RestOperations { *

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 @@ public interface RestOperations { *

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 @@ public interface RestOperations { *

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 */ ResponseEntity postForEntity(String url, Object request, Class responseType, Object... uriVariables) throws RestClientException; @@ -246,11 +246,11 @@ public interface RestOperations { *

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 */ ResponseEntity postForEntity(String url, Object request, Class responseType, Map uriVariables) throws RestClientException; @@ -261,10 +261,10 @@ public interface RestOperations { *

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 */ ResponseEntity postForEntity(URI url, Object request, Class responseType) throws RestClientException; @@ -277,7 +277,7 @@ public interface RestOperations { *

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 @@ public interface RestOperations { *

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,7 +300,7 @@ public interface RestOperations { *

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; @@ -315,12 +315,12 @@ public interface RestOperations { *

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 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 - * @since 5.0 */ T patchForObject(String url, Object request, Class responseType, Object... uriVariables) throws RestClientException; @@ -332,10 +332,11 @@ public interface RestOperations { *

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 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 patchForObject(String url, Object request, Class responseType, Map uriVariables) @@ -347,9 +348,10 @@ public interface RestOperations { *

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 PATCHed (may be {@code null}) * @param responseType the type of the return value * @return the converted object + * @since 4.3.5 * @see HttpEntity */ T patchForObject(URI url, Object request, Class responseType) throws RestClientException; @@ -418,7 +420,8 @@ public interface RestOperations { *

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 @@ -433,7 +436,8 @@ public interface RestOperations { *

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 @@ -447,7 +451,8 @@ public interface RestOperations { * 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 @@ -466,7 +471,7 @@ public interface RestOperations { * @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 @@ -485,7 +490,8 @@ public interface RestOperations { * * @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 @@ -504,7 +510,8 @@ public interface RestOperations { * * @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 diff --git a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java index eb17908300..358ffc4011 100644 --- a/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java +++ b/spring-web/src/main/java/org/springframework/web/client/RestTemplate.java @@ -458,6 +458,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat execute(url, HttpMethod.PUT, requestCallback, null); } + // PATCH @Override @@ -490,6 +491,7 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat return execute(url, HttpMethod.PATCH, requestCallback, responseExtractor); } + // DELETE @Override @@ -692,8 +694,8 @@ public class RestTemplate extends InterceptingHttpAccessor implements RestOperat * @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();