[[customizing-sdr.overriding-sdr-response-handlers]]
= Overriding Spring Data REST Response Handlers

Sometimes, you may want to write a custom handler for a specific resource. To take advantage of Spring Data REST's settings, message converters, exception handling, and more, use the `@RepositoryRestController` annotation instead of a standard Spring MVC `@Controller` or `@RestController`. Controllers annotated with `@RepositoryRestController` are served from the API base path defined in `RepositoryRestConfiguration.setBasePath`, which is used by all other RESTful endpoints (for example, `/api`). The following example shows how to use the `@RepositoryRestController` annotation:

====
[source,java]
----
@RepositoryRestController
public class ScannerController {

    private final ScannerRepository repository;

    @Autowired
    public ScannerController(ScannerRepository repo) { // <1>
        repository = repo;
    }

    @RequestMapping(method = GET, value = "/scanners/search/listProducers") // <2>
    public @ResponseBody ResponseEntity<?> getProducers() {
        List<String> producers = repository.listProducers(); // <3>

        //
        // do some intermediate processing, logging, etc. with the producers
        //

        CollectionModel<String> resources = CollectionModel.of(producers); // <4>

        resources.add(linkTo(methodOn(ScannerController.class).getProducers()).withSelfRel()); // <5>

        // add other links as needed

        return ResponseEntity.ok(resources); // <6>
    }

}
----

<1> This example uses constructor injection.
<2> This handler plugs in a custom handler for a Spring Data finder method.
<3> This handler uses the underlying repository to fetch data, but then does some form of post processing before returning the final data set to the client.
<4> The results of type T need to be wrapped up in a Spring HATEOAS `CollectionModel<T>` object to return a collection. `EntityModel<T>` or `RepresentationModel<T>` are suitable wrappers for a single item, respectively.
<5> Add a link back to this exact method as a `self` link.
<6> Returning the collection by using Spring MVC's `ResponseEntity` wrapper ensures that the collection is properly wrapped and rendered in the proper accept type.
====

`CollectionModel` is for a collection, while `EntityModel` -- or the more general class `RepresentationModel` -- is for a single item. These types can be combined. If you know the links for each item in a collection, use `CollectionModel<EntityModel<String>>` (or whatever the core domain type is rather than `String`). Doing so lets you assemble links for each item as well as for the whole collection.

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 `@RepositoryRestController` 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.
