This third part of my NetBeans and Payara MVC 1.0 series is about controllers in detail. An MVC controller is a resource method decorated by an @Controller annotation.
There are different options when using MVC Controllers. This blogpost explains how and when to use which type of controller method return types.
Controllers and Hybrid Classes
The @Controller annotation can be applied either on a class or on methods.
When the annotationis applied to methods The class is called hybrid class. Otherwise it's a controller class.
Note: The default produced media type (@Produces annotation) for MVC controller methods is text/html, but it can also be changed.
There are lots of different return types when working with @Controller methods or classes.
A controller method with a String as return type was used in the previous examples. The following snippet shows this one. The hello method puts my first- and lastname into the Person models object which is a RequestScoped CDI bean and the returned hello.jsp file displays this two Strings.
The return value of this method is the path to the corresponding view.
Note: A MVC controller always has to return a correct path to a view. Otherwise it will result in an HTTP 500 runtime error.
Another possible return type is the void one. When a controller method has a void return value it has to be annotated with the @View annotation. The following controller method is similar to the previous method with a String as return value.
In comparison to the String return type this one is one line of code longer. Although it's a little bit uncommon in comparison to JAX-RS and Java in general, in my opinion it's more clear because it well separates the corresponding view from the controller logic within the controller method.
The third return type is a JAX-RS Response. A JAX-RS return type gives you all access to HTTP responses and their headers.
In this example the Response is not that useful, because controller methods typically return a HTTP 200 status code. Therefore a String or a void return type should be used in such use cases.
However sometimes it is necessary to deviate from the HTTP 200. An example for a different HTTP code could be an erroneous input.
Note: It's also possible to put a View, a Viewable object or the result of Java type's toString() method object, but in most of the use cases this should be either a String or even a View object.
The last possible return type is a Viewable. A Viewable is a MVC class which encapsulates View paths like the String and void return types do. In addition to that it can also contain references to Models or CDI-based models (see previous post) or ViewEngine objects which can be used to use other View Engines than Java Server Pages.
This one also gives developers more flexibility than the return types of String or void, but in most of the cases this shouldn't be necessary. It can be used to implement additional view engines or something like that, but in my opinion there is no need for non-api developers to use this object. Additional view engines will be part of future early draft versions of the Ozark - MVC 1.0 Reference Implementation.
Controllers can be hybrid with JAX-RS methods and MVC controller methods. The default @Produces value of MVC controller methods is text/html, but it is also possible to return other types. There are four possible return types whereas a String and a void are the simplest and in my opinion they should be the prefered ones. Nevertheless there are use cases where the Response and the Viewable return type are necessary and useful.