JSR-371: MVC 1.0 TCK Coverage

An MVC controller is a JAX-RS [5] resource method decorated by @Controller

If this annotation is applied to a class, then all resource methods in it are regarded as controllers

Using the @Controller annotation on a subset of methods defines a hybrid class in which certain methods are controllers and others are traditional JAX-RS resource methods.

In particular, a return type of String is interpreted as a view path rather than text content

Moreover, the default media type for a response is assumed to be text/html, but otherwise can be declared using @Produces just like in JAX-RS

A controller method that returns void is REQUIRED to be decorated by @View

A string returned is interpreted as a view path

A JAX-RS Response whose entity's type is one of the above

The default view MUST be used only when such a non-void controller method returns a null value

All parameter types injectable in JAX-RS resources are also available in controllers

Likewise, injection of fields and properties is unrestricted and fully compatible with JAX-RS

MVC classes are REQUIRED to be CDI-managed beans only

It follows that a hybrid class that contains a mix of JAX-RS resource methods and MVC controllers must also be CDI managed

Like in JAX-RS, the default resource class instance lifecycle is per-request

In particular, CDI may need to create proxies when, for example, a per-request instance is as a member of a per-application instance

Returning a Response object gives applications full access to all the parts in a response, including the headers

Controllers can redirect clients by returning a Response instance using the JAX-RS API

MVC implementations are REQUIRED to support view paths prefixed by redirect: as a more concise way to trigger a client redirect

In either case, relative paths are resolved relative to the JAX-RS application path

MVC implementations SHOULD use the 303 (See other) status code for the redirect, but MAY prefer 302 (Found) if HTTP 1.0 compatibility is required.

A bean in request scope is available only during the processing of a single request

While a bean in session scope is available throughout an entire web session which can potentially span tens or even hundreds of requests

CDI beans in this scope are automatically created and destroyed by correlating a redirect and the request that follows

MVC provides view engines for JSP and Facelets out of the box, which support both types

Given that the view engine for JSPs supports @Named beans, all the controller needs to do is fill out the model and return the view

This will allow the view to access the greeting using the EL expression

Controllers can also use the Models map to pass data to the view

In a JSP, model properties are accessible via EL

URIs for these controller methods can be created with an EL expression

The controller method is referenced using the simple name of the controller class and the corresponding method name separated by #

If the URI contains path, query or matrix parameters, concrete values can be supplied using a map

MVC implementations MUST apply the corresponding URI encoding rules depending on whether the value is used in a query, path or matrix parameter

Therefore, applications can use the @UriRef annotation to define a stable and unique name for a controller method

You can enable the MVC specific data binding by adding a @MvcBinding annotation to the corresponding controller field or method parameter

Therefore, MVC implementations MUST support @MvcBinding with all JAX-RS binding annotations

An MVC implementation is required to invoke the matched controller method even if binding or validation errors occurred

Controllers can inject a request-scoped instance of BindingResult to access details about potential data binding errors

When converting values to these numeric Java types, MVC implementations MUST use the current request locale for parsing non-empty strings

Empty strings are either converted to null or to the default value of the corresponding primitive data type

When an MVC implementation converts a non-empty string to a boolean primitive type or the java.lang.Boolean wrapper type, it MUST convert both true and on to the boolean true and all others strings to false

Empty strings are converted to false in case of the primitive boolean type and to null for the wrapper type

The Csrf object is available to applications via the injectable MvcContext type or in EL as mvc.csrf

Applications may use the Csrf object to inject a hidden field in a form that can be validated upon submission

MVC implementations are REQUIRED to support CSRF tokens both as form fields (with the help of the application developer as shown above) and as HTTP headers

The default value of this property is CsrfOptions.EXPLICIT

Any other value than CsrfOptions.OFF will automatically inject a CSRF token as an HTTP header

The actual name of the header can be configured via the Csrf.CSRFHEADERNAME configuration property

The default name of the header is Csrf.DEFAULTCSRFHEADER_NAME

Automatic validation is enabled by setting this property to CsrfOptions.IMPLICIT, in which case all post requests must include either an HTTP header or a hidden field with the correct token

Finally, if the property is set to CsrfOptions.EXPLICIT then application developers must annotate controllers using @CsrfProtected to manually enable validation as shown in the following example

MVC implementations are required to support CSRF validation of tokens for controllers annotated with @POST and consuming the media type x-www-form-urlencoded

The MVC implementation MUST throw a javax.mvc.security.CsrfValidationException

The implementation MUST provide a default exception mapper for this exception which handles it by responding with a 403 (Forbidden) status code

Applications MAY provide a custom exception mapper for CsrfValidationException to change this default behavior

MVC applications can gain access to encoders through the MvcContext object

The methods defined by javax.mvc.security.Encoders can be used by applications to contextually encode data in an attempt to prevent XSS attacks

The events BeforeControllerEvent and AfterControllerEvent are fired around the invocation of a controller

Please note that AfterControllerEvent is always fired, even if the controller fails with an exception

The events BeforeProcessViewEvent and AfterProcessViewEvent are fired around this call

Please note that AfterProcessViewEvent is always fired, even if the view engine fails with an exception

The last event supported by MVC is ControllerRedirectEvent, which is fired just before the MVC implementation returns a redirect status code

Please note that this event MUST be fired after AfterControllerEvent

The controllers and providers that make up an application are configured via an application-supplied subclass of Application from JAX-RS

The path in the application's URL space in which MVC controllers live must be specified either using the @ApplicationPath annotation on the application subclass or in the web.xml as part of the url-pattern element

MVC applications can inject an instance of MvcContext to access configuration, security and path-related information

Instances of MvcContext are provided by implementations and are always in request scope

For convenience, the MvcContext instance is also available using the name mvc in EL

Such annotations are inherited by a corresponding sub-class or implementation class method provided that the method does not have any MVC or JAX-RS annotations of its own

Annotations on a super-class take precedence over those on an implemented interface

Implementations MUST provide built-in support for JSPs and Facelets view engines

Namely, any CDI bean that implements the javax.mvc.engine.ViewEngine interface MUST be considered as a possible target for processing by calling its supports method, discarding the engine if this method returns false

Implementations should perform the following steps while trying to find a suitable view engine for a view

In the case of the built-in view engines for JSPs and Facelets, entries in Models must be bound by calling HttpServletRequest.setAttribute(String, Object)

If the path is relative, does not start with /, implementations MUST resolve view paths relative to the view folder, which defaults to /WEB-INF/views/

If the path is absolute, no further processing is required

The request locale is available from MvcContext and can be used by controllers, view engines and other components

Every CDI bean implementing the LocaleResolver interface and visible to the application participates in the locale resolving algorithm

Implementations MUST use the following algorithm to resolve the request locale for each request

Every MVC implementation MUST provide a default locale resolver with a priority of 0 which resolves the request locale according to the following algorithm