How should the mappings be set up for a custom entity controller?

Question

The DXA documentation (Java) at https://docs.sdl.com/784837/748207/sdl-digital-experience-accelerator-2-2/creating-custom-models-and-controllers gives this example of how to create a custom entity controller

@Controller
@RequestMapping("/system/mvc/Example/ExampleController")
public class TestController extends BaseController {

    @Autowired
    private WebRequestContext webRequestContext;

    @RequestMapping(method = RequestMethod.GET, value = "DoStuff/{regionName}/{entityId}")
    public String handleGetEntity(HttpServletRequest request, 
                                  @PathVariable String regionName, 
                                  @PathVariable String entityId) throws ContentProviderException {

        return "Hello world";
    }
}

So we have two RequestMapping annotations, the first on the class:

@RequestMapping("/system/mvc/Example/ExampleController")

and the second on the method

@RequestMapping(method = RequestMethod.GET, value = "DoStuff/{regionName}/{entityId}")

I'm assuming that the first is used to allow the framework to locate the right controller. In this case if I have a module initialiser whose getAreaName() returns "Foo" and for which there is a @RegisteredViewModel with controllerName = "Bar", then presumably the annotation on my controller class should be:

@RequestMapping("/system/mvc/Foo/Bar")

Is this correct? Is the name of the class itself also relevant? Are other elements necessary in the mapping?

In the second mapping (on the method) what does "DoStuff" mean? Is "regionName" the name of the region, or the area.

Is there any other documentation available that I might have missed? Or examples?

Answer 1

It seems that my surmise about the @RequestMapping for the class was correct. For the method mapping, "DoStuff" doesn't seem to make any sense at all. I now have an implementation where handleGetEntity gets called. The signature looks like this:

@RequestMapping(value = "Entity" + "/{entityId}")
public String handleGetEntity(HttpServletRequest request, 
                              @PathVariable String entityId ) 
                              throws ContentProviderException {

It turns out that the default Controller Action is "Entity", unless you override this in your Component Template metadata. I hope someone will correct me if I'm wrong, but it looks like this is what gets picked up by the method mapping.

Answer 2

I can imagine you get confused by the example in the documentation; it looks rather dubious indeed.

For a real-life, working and tested example see: https://github.com/sdl/dxa-modules/blob/master/webapp-java/dxa-module-search/src/main/java/com/sdl/dxa/modules/search/controller/SearchController.java