Jakarta MVC Specification

MVC

Specification: Jakarta MVC Specification

Version: 2.1

Status: Final Release

Release: September 05, 2022

  1
2
3
4
5
6
7

  package com.example.hello;

public class Hello {
    public static void main(String args[]){
        System.out.println("Hello World");
    }
}

  1
2
3
4
5
6
7
8
9

  @Path("hello")
public class HelloController {

    @GET
    @Controller
    public String hello(){
        return "hello.jsp";
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

  @Controller
@Path("hello")
public class HelloController {

    @GET @Path("void")
    @View("hello.jsp")
    public void helloVoid() {
    }

    @GET @Path("string")
    public String helloString() {
        return "hello.jsp";
    }

    @GET @Path("response")
    public Response helloResponse() {
        return Response.status(Response.Status.OK)
            .entity("hello.jsp")
            .build();
    }
}

  1
2
3
4
5
6
7
8
9
10

  @GET
@Controller
public Response getById(@PathParam("id") String id) {
    if (id.length() == 0) {
        return Response.status(Response.Status.BAD_REQUEST)
            .entity("error.jsp")
            .build();
    }
    //...
}

  1
2
3
4
5

  @GET
@Controller
public Response redirect() {
    return Response.seeOther(URI.create("see/here")).build();
}

  1
2
3
4
5

  @GET
@Controller
public String redirect() {
    return "redirect:see/here";
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

  @Controller
@Path("submit")
public class MyController {

    @Inject
    private MyBean myBean;

    @POST
    public String post() {
        myBean.setValue("Redirect about to happen");
        return "redirect:/submit";
    }

    @GET
    public String get() {
        return "mybean.jsp"; // mybean.value accessed in Jakarta Server Page
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  @Named("greeting")
@RequestScoped
public class Greeting {

    private String message;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
    //...
}

  1
2
3
4
5
6
7
8
9
10
11
12
13

  @Path("hello")
public class HelloController {

    @Inject
    private Greeting greeting;

    @GET
    @Controller
    public String hello() {
        greeting.setMessage("Hello there!");
        return "hello.jsp";
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13

  @Path("hello")
public class HelloController {

    @Inject
    private Models models;

    @GET
    @Controller
    public String hello() {
        models.put("greeting", new Greeting("Hello there!"));
        return "hello.jsp";
    }
}

  1
2
3
4
5
6
7
8
9

  <!DOCTYPE html>
<html>
    <head>
        <title>Hello</title>
    </head>
    <body>
        <h1>${greeting.message}</h1>
    </body>
</html>

  1
2
3
4
5
6
7
8
9

  <!DOCTYPE html>
<html lang="en" xmlns:h="http://xmlns.jcp.org/jsf/html">
    <h:head>
        <title>Hello</title>
    </h:head>
    <h:body>
        <h:outputText value="#{greeting.message}" />
    </h:body>
</html>

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

  @Controller
@Path("books")
public class BookController {

    @GET
    public String list() {
      // ...
    }

    @GET
    @Path("{id}")
    public String detail( @PathParam("id") long id ) {
      // ...
    }

}

<!-- /myapp/mvc/books -->
${mvc.uri('BookController#list')}

<!-- /myapp/mvc/books/1234 -->
${mvc.uri('BookController#detail', { 'isbn': 1234 })}

  1
2
3
4
5
6
7
8
9
10
11
12
13

  @Controller
@Path("books")
public class BookController {

    @GET
    @UriRef("book-list")
    public String list() {
      // ...
    }

    // ...

}

<!-- /myapp/mvc/books -->
${mvc.uri('book-list')}

  1
2
3
4
5
6
7
8
9
10
11
12

  @Path("form")
public class FormResource {

    @FormParam("age")
    @Min(18)
    private int age;

    @POST
    public Response handlePost() {
        // ...
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14

  @Controller
@Path("form")
public class FormController {

    @MvcBinding
    @FormParam("age")
    @Min(18)
    private int age;

    @POST
    public String processForm() {
        // ...
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

  @Controller
@Path("form")
public class FormController {

    @MvcBinding
    @FormParam("age")
    @Min(18)
    private int age;

    @Inject
    private BindingResult bindingResult;

    @Inject
    private Models models;

    @POST
    public String processForm() {

        if( bindingResult.isFailed() ) {
            models.put( "errors", bindingResult.getAllMessages() );
            return "form.jsp";
        }

        // process the form request

    }
}

<img src="http://yourbank.com/transfer?from=yours&to=mine&sum=1000000">

  1
2
3
4
5
6
7
8
9
10
11
12

  <html>
    <head>
        <title>CSRF Protected Form</title>
    </head>
    <body>
        <form action="csrf" method="post" accept-charset="utf-8">
            <input type="submit" value="Click here"/>
            <input type="hidden" name="${mvc.csrf.name}"
                value="${mvc.csrf.token}"/>
        </form>
    </body>
</html>

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

  @Path("csrf")
@Controller
public class CsrfController {

    @GET
    public String getForm() {
        return "csrf.jsp"; // Injects CSRF token
    }

    @POST
    @CsrfProtected // Required for CsrfOptions.EXPLICIT
    public void postForm(@FormParam("greeting") String greeting) {
        // Process greeting
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

  /**
 * <p>Event fired before a controller is called but after it has been matched.</p>
 *
 * <p>For example:
 * <pre><code>    public class EventObserver {
 *         public void beforeControllerEvent(&#64;Observes BeforeControllerEvent e) {
 *            ...
 *        }
 *    }</code></pre>
 *
 * @author Santiago Pericas-Geertsen
 * @author Ivar Grimstad
 * @see jakarta.enterprise.event.Observes
 * @since 1.0
 */
public interface BeforeControllerEvent extends MvcEvent {

    /**
     * Access to the current request URI information.
     *
     * @return URI info.
     * @see jakarta.ws.rs.core.UriInfo
     */
    UriInfo getUriInfo();

    /**
     * Access to the current request controller information.
     *
     * @return resources info.
     * @see jakarta.ws.rs.container.ResourceInfo
     */
    ResourceInfo getResourceInfo();
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

  /**
 * <p>Event fired after a controller method returns. This event is always fired,
 * even if the controller methods fails with an exception. Must be fired after
 * {@link jakarta.mvc.event.BeforeControllerEvent}.</p>
 *
 * <p>For example:
 * <pre><code>    public class EventObserver {
 *         public void afterControllerEvent(&#64;Observes AfterControllerEvent e) {
 *            ...
 *        }
 *    }</code></pre>
 *
 * @author Santiago Pericas-Geertsen
 * @author Christian Kaltepoth
 * @author Ivar Grimstad
 * @see jakarta.enterprise.event.Observes
 * @since 1.0
 */
public interface AfterControllerEvent extends MvcEvent {

    /**
     * Access to the current request URI information.
     *
     * @return URI info.
     * @see jakarta.ws.rs.core.UriInfo
     */
    UriInfo getUriInfo();

    /**
     * Access to the current request controller information.
     *
     * @return resources info.
     * @see jakarta.ws.rs.container.ResourceInfo
     */
    ResourceInfo getResourceInfo();
}

  1
2
3
4
5
6
7
8
9
10
11
12

  @ApplicationScoped
public class EventObserver {

    public void onBeforeController(@Observes BeforeControllerEvent e) {
        System.out.println("URI: " + e.getUriInfo().getRequestUri());
    }

    public void onAfterController(@Observes AfterControllerEvent e) {
        System.out.println("Controller: " +
        e.getResourceInfo().getResourceMethod());
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

  /**
 * <p>Event fired after a view engine has been selected but before its
 * {@link jakarta.mvc.engine.ViewEngine#processView(jakarta.mvc.engine.ViewEngineContext)}
 * method is called. Must be fired after {@link jakarta.mvc.event.ControllerRedirectEvent},
 * or if that event is not fired, after {@link jakarta.mvc.event.AfterControllerEvent}.</p>
 *
 * <p>For example:
 * <pre><code>    public class EventObserver {
 *         public void beforeProcessView(&#64;Observes BeforeProcessViewEvent e) {
 *            ...
 *        }
 *    }</code></pre>
 *
 * @author Santiago Pericas-Geertsen
 * @author Ivar Grimstad
 * @see jakarta.enterprise.event.Observes
 * @since 1.0
 */
public interface BeforeProcessViewEvent extends MvcEvent {

    /**
     * Returns the view being processed.
     *
     * @return the view.
     */
    String getView();

    /**
    * Returns the {@link jakarta.mvc.engine.ViewEngine} selected by the implementation.
            *
            * @return the view engine selected.
            */
    Class<? extends ViewEngine> getEngine();
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

  /**
 * <p>Event fired after the view engine method
 * {@link jakarta.mvc.engine.ViewEngine#processView(jakarta.mvc.engine.ViewEngineContext)}
 * returns. This event is always fired, even if the view engine fails with an exception.
 * Must be fired after {@link jakarta.mvc.event.BeforeProcessViewEvent}.</p>
 *
 * <p>For example:
 * <pre><code>    public class EventObserver {
 *         public void afterProcessView(&#64;Observes AfterProcessViewEvent e) {
 *            ...
 *        }
 *    }</code></pre>
 *
 * @author Santiago Pericas-Geertsen
 * @author Christian Kaltepoth
 * @author Ivar Grimstad
 * @see jakarta.enterprise.event.Observes
 * @since 1.0
 */
public interface AfterProcessViewEvent extends MvcEvent {

    /**
     * Returns the view being processed.
     *
     * @return the view.
     */
    String getView();

    /**
     * Returns the {@link jakarta.mvc.engine.ViewEngine} selected by the implementation.
     *
     * @return the view engine selected.
     */
    Class<? extends ViewEngine> getEngine();
}

  1
2
3
4
5
6
7
8
9
10
11

  @ApplicationScoped
public class EventObserver {

    public void onBeforeProcessView(@Observes BeforeProcessViewEvent e) {
        // ...
    }

    public void onAfterProcessView(@Observes AfterProcessViewEvent e) {
        // ...
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12

  @ApplicationScoped
public class EventObserver {

    @Inject
    private EventBean eventBean;

    public void onBeforeProcessView(@Observes BeforeProcessViewEvent e) {
        eventBean.setView(e.getView());
        eventBean.setEngine(e.getEngine());
    }
    // ...
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

  /**
 * <p>Event fired when a controller triggers a redirect. Only the
 * status codes 301 (moved permanently), 302 (found), 303 (see other) and
 * 307 (temporary redirect) are REQUIRED to be reported. Note that the
 * JAX-RS methods
 * {@link jakarta.ws.rs.core.Response#seeOther(java.net.URI)}} and
 * {@link jakarta.ws.rs.core.Response#temporaryRedirect(java.net.URI)}}
 * use the status codes to 303 and 307, respectively. Must be
 * fired after {@link jakarta.mvc.event.AfterControllerEvent}.</p>
 *
 * <p>For example:
 * <pre><code>    public class EventObserver {
 *         public void onControllerRedirect(&#64;Observes ControllerRedirectEvent e) {
 *            ...
 *        }
 *    }</code></pre>
 *
 * @author Santiago Pericas-Geertsen
 * @author Ivar Grimstad
 * @see jakarta.enterprise.event.Observes
 * @since 1.0
 */
public interface ControllerRedirectEvent extends MvcEvent {

    /**
     * Access to the current request URI information.
     *
     * @return URI info.
     * @see jakarta.ws.rs.core.UriInfo
     */
    UriInfo getUriInfo();

    /**
     * Access to the current request controller information.
     *
     * @return resources info.
     * @see jakarta.ws.rs.container.ResourceInfo
     */
    ResourceInfo getResourceInfo();

    /**
     * The target of the redirection.
     *
     * @return URI of redirection.
     */
    URI getLocation();
}

<a href="${mvc.basePath}/books">Click here</a>

  1
2
3
4
5
6
7
8
9
10

  @ApplicationPath("resources")
public class MyApplication extends Application {

    @Override
    public Map<String, Object> getProperties() {
        final Map<String, Object> map = new HashMap<>();
        map.put(ViewEngine.VIEW_FOLDER, "/jsp/");
        return map;
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

/**
 * View engines are responsible for processing views and are discovered
 * using Jakarta Contexts and Dependency Injection. Implementations must look up all instances of this interface,
 * and process a view as follows:
 * <ol>
 * <li>Gather the set of candidate view engines by calling {@link #supports(String)}
 * and discarding engines that return <code>false</code>.</li>
 * <li>Sort the resulting set of candidates using priorities. View engines
 * can be decorated with {@link jakarta.annotation.Priority} to indicate
 * their priority; otherwise the priority is assumed to be {@link ViewEngine#PRIORITY_APPLICATION}.</li>
 * <li>If more than one candidate is available, choose one in an
 * implementation-defined manner.</li>
 * <li>Fire a {@link jakarta.mvc.event.BeforeProcessViewEvent} event.</li>
 * <li>Call method {@link #processView(ViewEngineContext)} to process view.</li>
 * <li>Fire a {@link jakarta.mvc.event.AfterProcessViewEvent} event.</li>
 * </ol>
 * The default view engines for Jakarta Server Pages and Facelets use file extensions to determine
 * support. Namely, the default Jakarta Server Pages view engine supports views with extensions <code>jsp</code>
 * and <code>jspx</code>, and the one for Facelets supports views with extension
 * <code>xhtml</code>.
 *
 * @author Santiago Pericas-Geertsen
 * @author Ivar Grimstad
 * @see jakarta.annotation.Priority
 * @see jakarta.mvc.event.BeforeProcessViewEvent
 * @since 1.0
 */
@SuppressWarnings("unused")
public interface ViewEngine {

    /**
     * Name of property that can be set to override the root location for views in an archive.
     *
     * @see jakarta.ws.rs.core.Application#getProperties()
     */
    String VIEW_FOLDER = "jakarta.mvc.engine.ViewEngine.viewFolder";

    /**
     * Default value for property {@link #VIEW_FOLDER}.
     */
    String DEFAULT_VIEW_FOLDER = "/WEB-INF/views/";

    /**
     * Priority for all built-in view engines.
     */
    int PRIORITY_BUILTIN = 1000;

    /**
     * Recommended priority for all view engines provided by frameworks built
     * on top of MVC implementations.
     */
    int PRIORITY_FRAMEWORK = 2000;

    /**
     * Recommended priority for all application-provided view engines (default).
     */
    int PRIORITY_APPLICATION = 3000;

    /**
     * Returns <code>true</code> if this engine can process the view or <code>false</code>
     * otherwise.
     *
     * @param view the view.
     * @return outcome of supports test.
     */
    boolean supports(String view);

    /**
     * <p>Process a view given a {@link jakarta.mvc.engine.ViewEngineContext}. Processing
     * a view involves <i>merging</i> the model and template data and writing
     * the result to an output stream.</p>
     *
     * <p>Following the Jakarta EE threading model, the underlying view engine implementation
     * must support this method being called by different threads. Any resources allocated
     * during view processing must be released before the method returns.</p>
     *
     * @param context the context needed for processing.
     * @throws ViewEngineException if an error occurs during processing.
     */
    void processView(ViewEngineContext context) throws ViewEngineException;
}

  1
2
3
4
5
6
7
8
9

  <servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>jakarta.faces.webapp.FacesServlet</servlet-class>
    <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
    <servlet-name>Faces Servlet</servlet-name>
    <url-pattern>*.xhtml</url-pattern>
</servlet-mapping>

  1
2
3
4
5
6
7
8
9
10
11
12
13

  @Controller
@Path("/foobar")
public class MyController {

    @Inject
    private MvcContext mvc;

    @GET
    public String get() {
        Locale locale = mvc.getLocale();
        NumberFormat format = NumberFormat.getInstance(locale);
    }
}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50

/**
 * Locale resolvers are used to determine the locale of the current request and are discovered
 * using Jakarta Contexts and Dependency Injection.
 *
 * The Jakarta MVC implementation is required to resolve the locale for each request following this
 * algorithm:
 *
 * <ol>
 * <li>Gather the set of all implementations of this interface available for injection via
 * CDI.</li>
 * <li>Sort the set of implementations using priorities in descending order. Locale resolvers
 * can be decorated with {@link jakarta.annotation.Priority} to indicate their priority. If no
 * priority is explicitly defined, the priority is assumed to be <code>1000</code>.</li>
 * <li>Call the method {@link #resolveLocale(LocaleResolverContext)}. If the resolver returns
 * a valid locale, use this locale as the request locale. If the resolver returns
 * <code>null</code>, proceed with the next resolver in the ordered set.</li>
 * </ol>
 *
 * Controllers, view engines and other components can access the resolved locale by calling
 * {@link MvcContext#getLocale()}.
 *
 * The MVC implementation is required to provide a default locale resolver with a priority
 * of <code>0</code> which uses the <code>Accept-Language</code> request header to obtain the
 * locale. If resolving the locale this way isn't possible, the default resolver must return
 * {@link Locale#getDefault()}.
 *
 * @author Christian Kaltepoth
 * @author Ivar Grimstad
 * @see jakarta.mvc.locale.LocaleResolverContext
 * @see MvcContext#getLocale()
 * @see java.util.Locale
 * @since 1.0
 */
public interface LocaleResolver {

    /**
     * <p>Resolve the locale of the current request given a {@link LocaleResolverContext}.</p>
     *
     * <p>If the implementation is able to resolve the locale for the request, the corresponding
     * locale must be returned. If the implementation cannot resolve the locale, it must return
     * <code>null</code>. In this case the resolving process will continue with the next
     * resolver.</p>
     *
     * @param context the context needed for processing.
     * @return The resolved locale or <code>null</code>.
     */
    Locale resolveLocale(LocaleResolverContext context);

}

  1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

  public final class FormMethodOverwriter {

    /**
     * Property that can be used to enable the Form method overwrite mechanism for an application.
     * Values of this property must be of type {@link FormMethodOverwriter.Options}.
     */
    public static final String FORM_METHOD_OVERWRITE = "jakarta.mvc.form.FormMethodOverwrite";

    /**
     * Property that can be used to configure the name of the hidden form input to get the targeted HTTP method.
     */
    public static final String HIDDEN_FIELD_NAME = "jakarta.mvc.form.HiddenFieldName";

    /**
     * The default name of the hidden form field used to overwrite the HTTP method.
     */
    public static final String DEFAULT_HIDDEN_FIELD_NAME = "_method";

    /**
     * Options for property {@link FormMethodOverwriter#FORM_METHOD_OVERWRITE}.
     */
    public enum Options {
        /**
         * Form method overwrite is not enabled.
         */
        DISABLED,

        /**
         * Form method overwrite is enabled. Each request will be checked for potential overwrites.
         */
        ENABLED
    }
}

Goal 1	Leverage existing Jakarta EE technologies like Jakarta Contexs and Dependency Injecttion [2] and Jakarta Bean Validation [3].
Goal 2	Define a solid core to build MVC applications without necessarily supporting all the features in its first version.
Goal 3	Build on top of Jakarta RESTful Web Services for the purpose of re-using its matching and binding layers.
Goal 4	Provide built-in support for Jakarta Server Pages and Facelets view languages.

Non-Goal 1	Define a new view (template) language and processor.
Non-Goal 2	Support standalone implementations of MVC running outside of Jakarta EE.
Non-Goal 3	Support REST services not based on Jakarta RESTful Web Services.
Non-Goal 4	Provide built-in support for view languages that are not part of Jakarta EE.

Binding Error	This type occurs if Jakarta RESTful Web Services is unable to convert the submitted value into the desired target Java type. For the resource shown above, such an error will be thrown if the user submits some arbitrary string like `foobar` which cannot be converted into an integer.
Validation Error	If the submitted value can be converted into the target type, Jakarta RESTful Web Services will validate the data according to the Bean Validation constraints. In our example submitting the value 16 would be considered invalid and therefore result in a constraint violation.

Jakarta MVC Specification

License

Copyright

Eclipse Foundation Specification License

Disclaimers

1. Introduction

1.1. Goals

1.2. Non-Goals

1.3. Additional Information

1.4. Terminology

1.5. Conventions

1.6. Acknowledgements for version 2.0

1.7. Acknowledgements for version 1.1

1.8. Acknowledgements for version 1.0

1.8.1. Specification Leads

1.8.2. Expert Group Members

1.8.3. Contributors

2. Models, Views and Controllers

2.1. Controllers

2.1.1. Controller Instances

2.1.2. Response

2.1.3. Redirect and @RedirectScoped

2.2. Models

2.3. Views

2.3.1. Building URIs in a View

3. Data Binding

3.1. Introduction

3.2. @MvcBinding annotation

3.3. Error handling with BindingResult

3.4. Converting to Java types

3.4.1. Numeric types

3.4.2. Boolean type

3.4.3. Other types

4. Security

4.1. Introduction

4.2. Cross-site Request Forgery

4.3. Cross-site Scripting

5. Events

5.1. Observers

6. Applications

6.1. MVC Applications

6.2. MVC Context

6.3. Providers in MVC

6.4. Annotation Inheritance

6.5. Configuration in MVC

7. View Engines

7.1. Introduction

7.2. Selection Algorithm

7.3. FacesServlet

8. Internationalization

8.1. Introduction

8.2. Resolving Algorithm

8.3. Default Locale Resolver

9. Form method override

9.1. Introduction

9.2. Resolving Algorithm

Appendix A: Summary of Annotations

Appendix B: Revision History

Bibliography