MVC 1.0: Model-View-Controller Specification

The following are goals of the API:

The following are non-goals of the API:

It is worth noting that, even though a standalone implementation of MVC that runs outside of Java EE is a non-goal, this specification shall not intentionally prevent implementations to run in other environments, provided that those environments include support for all the EE technologies required by MVC.

The issue tracking system for this specification can be found at:

https://github.com/mvc-spec/mvc-spec/issues

The corresponding Javadocs can be found online at:

https://www.mvc-spec.org/spec/

The reference implementation can be obtained from:

https://www.mvc-spec.org/krazo/

The expert group seeks feedback from the community on any aspect of this specification, please send comments to:

jsr371-users@googlegroups.com

Most of the terminology used in this specification is borrowed from other specifications such as JAX-RS and CDI. We use the terms per-request and request-scoped as well as per-application and application-scoped interchangeably.

The keywords `MUST', `MUST NOT', `REQUIRED', `SHALL', `SHALL NOT', `SHOULD', `SHOULD NOT', `RECOMMENDED', `MAY', and `OPTIONAL' in this document are to be interpreted as described in RFC 2119 [4].

Java code and sample data fragments are formatted as shown below:

URIs of the general form http://example.org/…​ and http://example.com/…​ represent application or context-dependent URIs.

All parts of this specification are normative, with the exception of examples, notes and sections explicitly marked as `Non-Normative'. Non-normative notes are formatted as shown below.

The following table lists the current and former specification leads:

This specification is being developed as part of JSR 371 under the Java Community Process. The following are the present expert group members:

The following are former members of the expert group:

The following are the contributors of the specification:

During the course of this JSR we received many excellent suggestions. Special thanks to Marek Potociar, Dhiru Pandey and Ed Burns, all from Oracle. In addition, to everyone in the user’s alias that followed the expert discussions and provided feedback, including Peter Pilgrim, Ivar Grimstad, Jozef Hartinger, Florian Hirsch, Frans Tamura, Rahman Usta, Romain Manni-Bucau, Alberto Souza, among many others.

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.

A simple hello-world controller can be defined as follows:

In this example, hello is a controller method that returns a path to a JavaServer Page (JSP). The semantics of controller methods differ slightly from 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’s method return type determines how its result is processed:

The following class defines equivalent controller methods:

Controller methods that return a non-void type may also be decorated with @View as a way to specify a default view for the controller. The default view MUST be used only when such a non-void controller method returns a null value.

Note that, even though controller methods return types are restricted as explained above, MVC does not impose any restrictions on parameter types available to controller methods: i.e., 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. Note the restrictions explained in Section Controller Instances.

Controller methods handle a HTTP request directly. Sub-resource locators as described in the JAX-RS Specification [5] are not supported by MVC.

MVC controllers are responsible for combining data models and views (templates) to produce web application pages. This specification supports two kinds of models: the first is based on CDI @Named beans, and the second on the Models interface which defines a map between names and objects. MVC provides view engines for JSP and Facelets out of the box, which support both types. For all other view engines supporting the Models interface is mandatory, support for CDI @Named beans is OPTIONAL but highly RECOMMENDED.

Let us now revisit our hello-world example, this time also showing how to update a model. Since we intend to show the two ways in which models can be used, we define the model as a CDI @Named bean in request scope even though this is only necessary for the CDI case:

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. Access to the model is straightforward using CDI injection:

This will allow the view to access the greeting using the EL expression ${hello.greeting}.

Instead of using CDI beans annotated with @Named, controllers can also use the Models map to pass data to the view:

In this example, the model is given the same name as that in the @Named annotation above, but using the injectable Models map instead.

For more information about view engines see the View Engines section.

A view, sometimes also referred to as a template, defines the structure of the output page and can refer to one or more models. It is the responsibility of a view engine to process (render) a view by extracting the information in the models and producing the output page.

Here is the JSP page for the hello-world example:

In a JSP, model properties are accessible via EL [6]. In the example above, the property message is read from the greeting model whose name was either specified in a @Named annotation or used as a key in the Models map, depending on which controller from the Models section triggered this view’s processing.

Here is the corresponding example using Facelets instead of JSP:

JAX-RS provides support for binding request parameters (like form/query parameters) to resource fields or resource method parameters. Starting with JAX-RS 2.0, developers can also specify validation constraints using Bean Validation annotations. In this case submitted values are automatically validated against the given constraints and rejected if validation fails.

Let’s have a look at the following resource for an example:

This resource uses a @FormParam annotation to bind the value of the age form parameter to a resource field. It also uses the Bean Validation annotation @Min to specify a constraint on the value.

When JAX-RS binds the submitted data to the field, two types of errors are possible:

Unfortunately the JAX-RS data binding mechanism doesn’t work well for web applications:

MVC addresses the shortcomings of the standard JAX-RS data binding by providing a special data binding mode optimized for web applications. You can enable the MVC specific data binding by adding a @MvcBinding annotation to the corresponding controller field or method parameter.

The following example shows a controller which uses a MVC binding on a controller field.

Please note that usually @MvcBinding will be used with @FormParam and @QueryParam bindings, as they are very common in web application. However, depending on the specific use case, it may also be useful to use it with other parameter binding types. Therefore, MVC implementations MUST support @MvcBinding with all JAX-RS binding annotations.

The following sections will describe the differences from traditional JAX-RS data binding in detail.

As mentioned in the first section, JAX-RS data binding aborts request processing for any binding or validation error. This means, that a resource method will only be invoked if all bindings were successful.

MVC bindings handle such errors in a different way. 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. This allows controllers to handle such errors themselves, which typically means that human-readable error messages are presented to the user when the next view is rendered.

The following example shows a controller which uses BindingResult to handle data binding errors:

Please note that it is very important for a controller to actually check the BindingResult for errors if it uses MVC bindings. If a binding failed and the controller processes the value without checking for errors, the bound value may be empty or contain an invalid value.

MVC implementations SHOULD log a warning if a request created data binding errors but the controller didn’t invoke any method on BindingResult.

The standard JAX-RS data binding doesn’t work very well for web application, because it isn’t locale-aware and some standard HTML form elements submit data which cannot easily be bound to matching Java types (e.g. checkboxes are submitting on if checked and JAX-RS is expecting true for boolean values).

MVC implementations are required to apply the following data conversion rules if a binding is annotated with @MvcBinding.

Guarding against malicious attacks is a great concern for web application developers. In particular, MVC applications that accept input from a browser are often targetted by attackers. Two of the most common forms of attacks are cross-site request forgery (CSRF) and cross-site scripting (XSS). This chapter explores techniques to prevent these type of attacks with the aid of the MVC API.

Cross-site Request Forgery (CSRF) is a type of attack in which a user, who has a trust relationship with a certain site, is mislead into executing some commands that exploit the existence of such a trust relationship. The canonical example for this attack is that of a user unintentionally carrying out a bank transfer while visiting another site.

The attack is based on the inclusion of a link or script in a page that accesses a site to which the user is known or assumed to have been authenticated (trusted). Trust relationships are often stored in the form of cookies that may be active while the user is visiting other sites. For example, such a malicious site could include the following HTML snippet:

This will result in the browser executing a bank transfer in an attempt to load an image.

In practice, most sites require the use of form posts to submit requests such as bank transfers. The common way to prevent CSRF attacks is by embedding additional, difficult-to-guess data fields in requests that contain sensible commands. This additional data, known as a token, is obtained from the trusted site but unlike cookies it is never stored in the browser.

MVC implementations provide CSRF protection using the Csrf object and the @CsrfProtected annotation. The Csrf object is available to applications via the injectable MvcContext type or in EL as mvc.csrf. For more information about MvcContext, please refer to the MVC Context section.

Applications may use the Csrf object to inject a hidden field in a form that can be validated upon submission. Consider the following JSP:

The hidden field will be submitted with the form, giving the MVC implementation the opportunity to verify the token and ensure the validity of the post request.

Another way to convey this information to and from the client is via an HTTP header. 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 application-level property javax.mvc.security.CsrfProtection enables CSRF protection when set to one of the possible values defined in javax.mvc.security.Csrf.CsrfOptions. 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.CSRF_HEADER_NAME configuration property. The default name of the header is Csrf.DEFAULT_CSRF_HEADER_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; other media types and scenarios may also be supported but are OPTIONAL.

If CSRF protection is enabled for a controller method and the CSRF validation fails (because the token is either missing or invalid), 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.

Cross-site scripting (XSS) is a type of attack in which snippets of scripting code are injected and later executed when returned back from a server. The typical scenario is that of a website with a search field that does not validate its input, and returns an error message that includes the value that was submitted. If the value includes a snippet of the form <script>…​</script> then it will be executed by the browser when the page containing the error is rendered.

There are lots of different variations of this the XSS attack, but most can be prevented by ensuring that the data submitted by clients is properly sanitized before it is manipulated, stored in a database, returned to the client, etc. Data escaping/encoding is the recommended way to deal with untrusted data and prevent XSS attacks.

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 reader is referred to the Javadoc for this type for further information.

The package javax.mvc.event defines a number of event types that MUST be fired by implementations during the processing of a request. Implementations MAY extend this set and also provide additional information on any of the events defined by this specification. The reader is referred to the implementation’s documentation for more information on event support.

Observing events can be useful for applications to learn about the lifecycle of a request, perform logging, monitor performance, etc. 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.

Applications can monitor these events using an observer as shown next.

Observer methods in CDI are defined using the @Observes annotation on a parameter position. The class EventObserver is a CDI bean in application scope whose methods onBeforeController and onAfterController are called before and after a controller is called.

Each event includes additional information that is specific to the event; for example, the events shown in the example above allow applications to get information about the request URI and the resource (controller) selected.

The View Engines section describes the algorithm used by implementations to select a specific view engine for processing; after a view engine is selected, the method processView is called. 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.

These events can be observed in a similar manner:

To complete the example, let us assume that the information about the selected view engine needs to be conveyed to the client. To ensure that this information is available to a view returned to the client, the EventObserver class can inject and update the same request-scope bean accessed by such a view:

For more information about the interaction between views and models, the reader is referred to the Models section.

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.

CDI events fired by implementations are synchronous, so it is recommended that applications carry out only simple tasks in their observer methods, avoiding long-running computations as well as blocking calls. For a complete list of events, the reader is referred to the Javadoc for the javax.mvc.event package.

Event reporting requires the MVC implementations to create event objects before firing. In high-throughput systems without any observers the number of unnecessary objects created may not be insignificant. For this reason, it is RECOMMENDED for implementations to consider smart firing strategies when no observers are present.

An MVC application consists of one or more JAX-RS resources that are annotated with @Controller and, just like JAX-RS applications, zero or more providers. If no resources are annotated with @Controller, then the resulting application is a JAX-RS application instead. In general, everything that applies to a JAX-RS application also applies to an MVC application. Some MVC applications may be hybrid and include a mix of MVC controllers and JAX-RS resource methods.

The controllers and providers that make up an application are configured via an application-supplied subclass of Application from JAX-RS. An implementation MAY provide alternate mechanisms for locating controllers, but as in JAX-RS, the use of an Application subclass is the only way to guarantee portability.

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 SHOULD use a non-empty path or pattern: i.e., "/" or "/*" should be avoided whenever possible. The reason for this is that MVC implementations often forward requests to the Servlet container, and the use of the aforementioned values may result in the unwanted processing of the forwarded request by the JAX-RS servlet once again.

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.

As an example, a view can refer to a controller by using the base path available in the MvcContext object as follows:

For more information on security see the Chapter on Security; for more information about the MvcContext in general, refer to the Javadoc for the type.

Implementations are free to use their own providers in order to modify the standard JAX-RS pipeline for the purpose of implementing the MVC semantics. Whenever mixing implementation and application providers, care should be taken to ensure the correct execution order using priorities.

MVC applications MUST follow the annotation inheritance rules defined by JAX-RS. Namely, MVC annotations may be used on methods of a super-class or an implemented interface. 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: i.e., if a subclass or implementation method has any MVC or JAX-RS annotations then all of the annotations on the superclass or interface method are ignored.

Annotations on a super-class take precedence over those on an implemented interface. The precedence over conflicting annotations defined in multiple implemented interfaces is implementation dependent. Note that, in accordance to the JAX-RS rules, inheritance of class or interface annotations is not supported.

Implementations MUST support configuration via the native JAX-RS configuration mechanism but MAY support other configuration sources.

There are concrete configurations, that all MVC the implementations are REQUIRED the support such as:

Here’s a simple example of how you can configure a custom location for the view folder other than the /WEB-INF/views, simply by overwriting the getProperties method of the subclass Application:

A view engine is responsible for processing views. In this context, processing entails (i) locating and loading a view (ii) preparing any required models and (iii) rendering the view and writing the result back to the client.

Implementations MUST provide built-in support for JSPs and Facelets view engines. Additional engines may be supported via an extension mechanism based on CDI. 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.

This is the interface that must be implemented by all MVC view engines:

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

If a view engine that can process a view is not found, implementations SHOULD throw a corresponding exception and stop to process the request.

The processView method has all the information necessary for processing in the ViewEngineContext, including the view, a reference to Models, as well as the underlying OutputStream that can be used to send the result to the client.

Prior to the view render phase, all entries available in Models MUST be bound in such a way that they become available to the view being processed. The exact mechanism for this depends on the actual view engine implementation. 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). Calling this method ensures access to the named models from EL expressions.

A view returned by a controller method represents a path within an application archive. 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. It is recommended to use relative paths and a location under WEB-INF to prevent direct access to views as static resources.

Because Facelets support is not enabled by default, MVC applications that use Facelets are required to package a web.xml deployment descriptor with the following entry mapping the extension *.xhtml as shown next:

Alternatively to a web.xml deployment descriptor an empty faces-config.xml file can be placed in the WEB-INF folder to enable Facelets support.

It is worth noting that if you opt to use Facelets as a view technology for your MVC application, regular JSF post-backs will not be processed by the MVC runtime. The usage of <h:form /> and depending form components like <h:inputText /> is not recommended as they would be the entry point to a real JSF application.

Internationalization and localization are very important concepts for any web application framework. Therefore MVC has been designed to make supporting multiple languages and regional differences in applications very easy.

MVC defines the term request locale as the locale which is used for any locale-dependent operation within the lifecycle of a request. The request locale MUST be resolved exactly once for each request using the resolving algorithm described in the Resolving Algorithm section.

These locale-dependent operations include, but are not limited to:

The request locale is available from MvcContext and can be used by controllers, view engines and other components to perform operations which depend on the current locale. The example below shows a controller that uses the request locale to create a NumberFormat instance.

The following sections will explain the locale resolving algorithm and the default resolver provided by the MVC implementation.

The locale resolver is responsible to detect the request locale for each request processed by the MVC runtime. A locale resolver MUST implement the javax.mvc.locale.LocaleResolver interface which is defined like this:

There may be more than one locale resolver for a MVC application. Locale resolvers are discovered using CDI. 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:

Applications can either rely on the default locale resolver which is described in the Default Locale Resolver section or provide a custom resolver which implements some other strategy for resolving the request locale. A custom strategy could for example track the locale using the session, a query parameter or the server’s hostname.

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

Please note that applications can customize the locale resolving process by providing a custom locale resolver with a priority higher than 0. See the Resolving Algorithm section for details.