Jakarta MVC Specification

MVC

Specification: Jakarta MVC Specification

Version: 1.1

Status: Final Release

Release: September 23, 2020
package com.example.hello;

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

    @GET
    @Controller
    public String hello(){
        return "hello.jsp";
    }
}
@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();
    }
}
@GET
@Controller
public Response getById(@PathParam("id") String id) {
    if (id.length() == 0) {
        return Response.status(Response.Status.BAD_REQUEST)
            .entity("error.jsp")
            .build();
    }
    //...
}
@GET
@Controller
public Response redirect() {
    return Response.seeOther(URI.create("see/here")).build();
}
@GET
@Controller
public String redirect() {
    return "redirect:see/here";
}
@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
    }
}
@Named("greeting")
@RequestScoped
public class Greeting {

    private String message;

    public String getMessage() {
        return message;
    }

    public void setMessage(String message) {
        this.message = message;
    }
    //...
}
@Path("hello")
public class HelloController {

    @Inject
    private Greeting greeting;

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

    @Inject
    private Models models;

    @GET
    @Controller
    public String hello() {
        models.put("greeting", new Greeting("Hello there!"));
        return "hello.jsp";
    }
}
<!DOCTYPE html>
<html>
    <head>
        <title>Hello</title>
    </head>
    <body>
        <h1>${greeting.message}</h1>
    </body>
</html>
<!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>
@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 })}
@Controller
@Path("books")
public class BookController {

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

    // ...

}
<!-- /myapp/mvc/books -->
${mvc.uri('book-list')}
@Path("form")
public class FormResource {

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

    @POST
    public Response handlePost() {
        // ...
    }
}
@Controller
@Path("form")
public class FormController {

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

    @POST
    public String processForm() {
        // ...
    }
}
@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">
<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>
@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
    }
}
/**
 * <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
 * @see javax.enterprise.event.Observes
 * @since 1.0
 */
public interface BeforeControllerEvent extends MvcEvent {

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

    /**
     * Access to the current request controller information.
     *
     * @return resources info.
     * @see javax.ws.rs.container.ResourceInfo
     */
    ResourceInfo getResourceInfo();
}
/**
 * <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 javax.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
 * @see javax.enterprise.event.Observes
 * @since 1.0
 */
public interface AfterControllerEvent extends MvcEvent {

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

    /**
     * Access to the current request controller information.
     *
     * @return resources info.
     * @see javax.ws.rs.container.ResourceInfo
     */
    ResourceInfo getResourceInfo();
}
@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());
    }
}
/**
 * <p>Event fired after a view engine has been selected but before its
 * {@link javax.mvc.engine.ViewEngine#processView(javax.mvc.engine.ViewEngineContext)}
 * method is called. Must be fired after {@link javax.mvc.event.ControllerRedirectEvent},
 * or if that event is not fired, after {@link javax.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
 * @see javax.enterprise.event.Observes
 * @since 1.0
 */
public interface BeforeProcessViewEvent extends MvcEvent {

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

    /**
    * Returns the {@link javax.mvc.engine.ViewEngine} selected by the implementation.
            *
            * @return the view engine selected.
            */
    Class<? extends ViewEngine> getEngine();
}
/**
 * <p>Event fired after the view engine method
 * {@link javax.mvc.engine.ViewEngine#processView(javax.mvc.engine.ViewEngineContext)}
 * returns. This event is always fired, even if the view engine fails with an exception.
 * Must be fired after {@link javax.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
 * @see javax.enterprise.event.Observes
 * @since 1.0
 */
public interface AfterProcessViewEvent extends MvcEvent {

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

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

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

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

    @Inject
    private EventBean eventBean;

    public void onBeforeProcessView(@Observes BeforeProcessViewEvent e) {
        eventBean.setView(e.getView());
        eventBean.setEngine(e.getEngine());
    }
    // ...
}
/**
 * <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 javax.ws.rs.core.Response#seeOther(java.net.URI)}} and
 * {@link javax.ws.rs.core.Response#temporaryRedirect(java.net.URI)}}
 * use the status codes to 303 and 307, respectively. Must be
 * fired after {@link javax.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
 * @see javax.enterprise.event.Observes
 * @since 1.0
 */
public interface ControllerRedirectEvent extends MvcEvent {

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

    /**
     * Access to the current request controller information.
     *
     * @return resources info.
     * @see javax.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>
@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;
    }
}
/**
 * <p>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 javax.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 javax.mvc.event.BeforeProcessViewEvent} event.</li>
 *     <li>Call method {@link #processView(ViewEngineContext)} to process view.</li>
 *     <li>Fire a {@link javax.mvc.event.AfterProcessViewEvent} event.</li>
 * </ol>
 * <p>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>.</p>
 *
 * @author Santiago Pericas-Geertsen
 * @see javax.annotation.Priority
 * @see javax.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 javax.ws.rs.core.Application#getProperties()
     */
    String VIEW_FOLDER = "javax.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 javax.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;
}
<servlet>
    <servlet-name>Faces Servlet</servlet-name>
    <servlet-class>javax.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>
@Controller
@Path("/foobar")
public class MyController {

    @Inject
    private MvcContext mvc;

    @GET
    public String get() {
        Locale locale = mvc.getLocale();
        NumberFormat format = NumberFormat.getInstance(locale);
    }
}
/**
 * <p>Locale resolvers are used to determine the locale of the current request and are discovered
 * using Jakarta Contexts and Dependency Injection.</p>
 *
 * <p>The Jakarta MVC implementation is required to resolve the locale for each request following this
 * algorithm:</p>
 *
 * <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 javax.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>
 *
 * <p>Controllers, view engines and other components can access the resolved locale by calling
 * {@link MvcContext#getLocale()}.</p>
 *
 * <p>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()}.</p>
 *
 * @author Christian Kaltepoth
 * @see javax.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);

}

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 1.1

1.7. Acknowledgements for version 1.0

1.7.1. Specification Leads

1.7.2. Expert Group Members

1.7.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

Appendix A: Summary of Annotations

Bibliography