From f3b1d92c229a129ca63b124d76a671d357136b61 Mon Sep 17 00:00:00 2001 From: Oliver Drotbohm Date: Tue, 4 Jun 2019 23:32:14 +0200 Subject: [PATCH] DATAREST-1381 - Improve documentation around @RepositoryRestController. --- .../data/rest/webmvc/RepositoryRestController.java | 11 +++++++++++ .../asciidoc/overriding-sdr-response-handlers.adoc | 8 ++++++++ 2 files changed, 19 insertions(+) diff --git a/spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestController.java b/spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestController.java index 9326663c3..27e06a9fb 100644 --- a/spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestController.java +++ b/spring-data-rest-webmvc/src/main/java/org/springframework/data/rest/webmvc/RepositoryRestController.java @@ -21,11 +21,22 @@ import java.lang.annotation.Retention; import java.lang.annotation.RetentionPolicy; import java.lang.annotation.Target; +import org.springframework.orm.jpa.support.OpenEntityManagerInViewInterceptor; import org.springframework.stereotype.Component; +import org.springframework.web.servlet.HandlerMapping; /** * Annotation to demarcate Spring MVC controllers provided by Spring Data REST. Allows to easily detect them and exclude * them from standard Spring MVC handling. + *

+ * Note, that this annotation should only be used by application controllers that map to URIs that are managed by Spring + * Data REST as the get handled by a special {@link HandlerMapping} implementation that applies additional + * functionality: + *

* * @author Oliver Gierke */ diff --git a/src/main/asciidoc/overriding-sdr-response-handlers.adoc b/src/main/asciidoc/overriding-sdr-response-handlers.adoc index e6dfeb313..60efb10e9 100644 --- a/src/main/asciidoc/overriding-sdr-response-handlers.adoc +++ b/src/main/asciidoc/overriding-sdr-response-handlers.adoc @@ -48,6 +48,14 @@ public class ScannerController { IMPORTANT: In this example, the combined path is `RepositoryRestConfiguration.getBasePath()` + `/scanners/search/listProducers`. +[[customizing-sdr.overriding-sdr-response-handlers.annotations]] +== @RepositoryRestResource VS. @BasePathAwareController + If you are not interested in entity-specific operations but still want to build custom operations underneath `basePath`, such as Spring MVC views, resources, and others, use `@BasePathAwareController`. +If you're using `@RepositoryRestResource` on your custom controller, it will only handle the request if your request mappings blend into the URI space used by the repository. +It will also apply the following extra functionality to the controller methods: + +. CORS configuration according as defined for the repository mapped to the base path segment used in the request mapping of the handler method. +. Apply an `OpenEntityManagerInViewInterceptor` if JPA is used to make sure you can access properties marked as to be resolved lazily. WARNING: If you use `@Controller` or `@RestController` for anything, that code is totally outside the scope of Spring Data REST. This extends to request handling, message converters, exception handling, and other uses.