<?xml version="1.0" encoding="UTF-8"?>
<!--

    Copyright (c) 2016-2019 JSR 371 expert group and contributors

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

-->
<!-- Generated by tck-audit.xsl at October 03, 2020 (revision 1.1.0) -->
<specification xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xalan="http://xml.apache.org/xslt" xmlns:exslt="http://exslt.org/common" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://jboss.com/products/weld/tck/audit" xsi:schemaLocation="http://jboss.com/products/weld/tck/audit" name="Jakarta MVC Specification" version="1.1" id="mvc" generateSectionIds="true">
    <section id="Copyright" title="Copyright" level="1" xmlns="">
        <!-- 1 - COPYRIGHT -->
    </section>
    <section id="efsl" title="Eclipse Foundation Specification License" level="1" xmlns="">
        <!-- 2 - EFSL -->
    </section>
    <section id="disclaimers" title="Disclaimers" level="2" xmlns="">
        <!-- 2.1 - DISCLAIMERS -->
    </section>
    <section id="introduction" title="Introduction" level="1" xmlns="">
        <!-- 1 - INTRODUCTION -->
    </section>
    <section id="goals" title="Goals" level="2" xmlns="">
        <!-- 1.1 - GOALS -->
    </section>
    <section id="non_goals" title="Non-Goals" level="2" xmlns="">
        <!-- 1.2 - NON_GOALS -->
    </section>
    <section id="additional_information" title="Additional Information" level="2" xmlns="">
        <!-- 1.3 - ADDITIONAL_INFORMATION -->
    </section>
    <section id="terminology" title="Terminology" level="2" xmlns="">
        <!-- 1.4 - TERMINOLOGY -->
    </section>
    <section id="conventions" title="Conventions" level="2" xmlns="">
        <!-- 1.5 - CONVENTIONS -->
    </section>
    <section id="acks11" title="Acknowledgements for version 1.1" level="2" xmlns="">
        <!-- 1.6 - ACKS11 -->
    </section>
    <section id="acks10" title="Acknowledgements for version 1.0" level="2" xmlns="">
        <!-- 1.7 - ACKS10 -->
    </section>
    <section id="spec_leads" title="Specification Leads" level="3" xmlns="">
        <!-- 1.7.1 - SPEC_LEADS -->
    </section>
    <section id="expert_group" title="Expert Group Members" level="3" xmlns="">
        <!-- 1.7.2 - EXPERT_GROUP -->
    </section>
    <section id="contributors" title="Contributors" level="3" xmlns="">
        <!-- 1.7.3 - CONTRIBUTORS -->
    </section>
    <section id="mvc" title="Models, Views and Controllers" level="1" xmlns="">
        <!-- 2 - MVC -->
    </section>
    <section id="controllers" title="Controllers" level="2" xmlns="">
        <!-- 2.1 - CONTROLLERS -->
        <assertion id="ctrl-method">
            <text>A Jakarta MVC controller is a Jakarta RESTful Web Services [5] resource method decorated by @Controller</text>
        </assertion>
        <assertion id="ctrl-class">
            <text>If this annotation is applied to a class, then all resource methods in it are regarded as controllers</text>
        </assertion>
        <assertion id="ctrl-hybrid">
            <text>Using the @Controller annotation on a subset of methods defines a hybrid class in which certain methods are controllers and others are traditional Jakarta RESTful Web Services resource methods.</text>
        </assertion>
        <assertion id="return-string">
            <text>In particular, a return type of String is interpreted as a view path rather than text content</text>
        </assertion>
        <assertion id="default-mediatype">
            <text>Moreover, the default media type for a response is assumed to be text/html, but otherwise can be declared using @Produces just like in Jakarta RESTful Web Services</text>
        </assertion>
        <assertion id="return-void">
            <text>A controller method that returns void is REQUIRED to be decorated by @View</text>
        </assertion>
        <assertion id="return-string2">
            <text>A string returned is interpreted as a view path</text>
        </assertion>
        <assertion id="return-response">
            <text>A Jakarta RESTful Web Services Response whose entity's type is one of the above</text>
        </assertion>
        <assertion id="non-null-viewable">
            <text>The default view MUST be used only when such a non-void controller method returns a null value</text>
        </assertion>
        <assertion id="inject-param-types">
            <text>All parameter types injectable in Jakarta RESTful Web Services resources are also available in controllers</text>
        </assertion>
        <assertion id="inject-field-props">
            <text>Likewise, injection of fields and properties is unrestricted and fully compatible with Jakarta RESTful Web Services</text>
        </assertion>
    </section>
    <section id="controller_instances" title="Controller Instances" level="3" xmlns="">
        <!-- 2.1.1 - CONTROLLER_INSTANCES -->
        <assertion id="ctrl-cdi">
            <text>Jakarta MVC classes are REQUIRED to be CDI-managed beans only</text>
        </assertion>
        <assertion id="ctrl-cdi-hybrid">
            <text>It follows that a hybrid class that contains a mix of Jakarta RESTful Web Services resource methods and Jakarta MVC controllers must also be CDI managed</text>
        </assertion>
        <assertion id="request-scope-default">
            <text>Like in Jakarta RESTful Web Services, the default resource class instance lifecycle is per-request</text>
        </assertion>
        <assertion id="scope-proxy">
            <text>In particular, CDI may need to create proxies when, for example, a per-request instance is as a member of a per-application instance</text>
        </assertion>
    </section>
    <section id="response" title="Response" level="3" xmlns="">
        <!-- 2.1.2 - RESPONSE -->
        <assertion id="response-header">
            <text>Returning a Response object gives applications full access to all the parts in a response, including the headers</text>
        </assertion>
    </section>
    <section id="redirect" title="Redirect and @RedirectScoped" level="3" xmlns="">
        <!-- 2.1.3 - REDIRECT -->
        <assertion id="redirect-response">
            <text>Controllers can redirect clients by returning a Response instance using the Jakarta RESTful Web Services API</text>
        </assertion>
        <assertion id="redirect-prefix">
            <text>Jakarta MVC implementations are REQUIRED to support view paths prefixed by redirect: as a more concise way to trigger a client redirect</text>
        </assertion>
        <assertion id="redirect-relative">
            <text>In either case, relative paths are resolved relative to the Jakarta RESTful Web Services application path</text>
        </assertion>
        <assertion id="redirect-303-302">
            <text>Jakarta 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.</text>
        </assertion>
        <assertion id="scope-request">
            <text>A bean in request scope is available only during the processing of a single request</text>
        </assertion>
        <assertion id="scope-session">
            <text>While a bean in session scope is available throughout an entire web session which can potentially span tens or even hundreds of requests</text>
        </assertion>
        <assertion id="scope-redirect">
            <text>CDI beans in this scope are automatically created and destroyed by correlating a redirect and the request that follows</text>
        </assertion>
    </section>
    <section id="models" title="Models" level="2" xmlns="">
        <!-- 2.2 - MODELS -->
        <assertion id="builtin-both-models">
            <text>Jakarta MVC provides view engines for Jakarta Server Pages and Facelets out of the box, which support both types</text>
        </assertion>
        <assertion id="cdi-model-inject">
            <text>Given that the view engine for Jakarta Server Pages supports @Named beans, all the controller needs to do is fill out the model and return the view</text>
        </assertion>
        <assertion id="cdi-model-el">
            <text>This will allow the view to access the greeting using the EL expression</text>
        </assertion>
        <assertion id="models-inject">
            <text>Controllers can also use the Models map to pass data to the view</text>
        </assertion>
    </section>
    <section id="views" title="Views" level="2" xmlns="">
        <!-- 2.3 - VIEWS -->
        <assertion id="jsp-el">
            <text>In Jakarta Server Pages, model properties are accessible via EL</text>
        </assertion>
    </section>
    <section id="mvc_uri" title="Building URIs in a View" level="3" xmlns="">
        <!-- 2.3.1 - MVC_URI -->
        <assertion id="el-access">
            <text>URIs for these controller methods can be created with an EL expression</text>
        </assertion>
        <assertion id="class-method-name">
            <text>The controller method is referenced using the simple name of the controller class and the corresponding method name separated by #</text>
        </assertion>
        <assertion id="param-map">
            <text>If the URI contains path, query or matrix parameters, concrete values can be supplied using a map</text>
        </assertion>
        <assertion id="uri-encoding">
            <text>Jakarta MVC implementations MUST apply the corresponding URI encoding rules depending on whether the value is used in a query, path or matrix parameter</text>
        </assertion>
        <assertion id="uri-ref">
            <text>Therefore, applications can use the @UriRef annotation to define a stable and unique name for a controller method</text>
        </assertion>
    </section>
    <section id="data_binding" title="Data Binding" level="1" xmlns="">
        <!-- 3 - DATA_BINDING -->
    </section>
    <section id="data_binding_intro" title="Introduction" level="2" xmlns="">
        <!-- 3.1 - DATA_BINDING_INTRO -->
    </section>
    <section id="mvc_binding_annotation" title="@MvcBinding annotation" level="2" xmlns="">
        <!-- 3.2 - MVC_BINDING_ANNOTATION -->
        <assertion id="mvc-binding">
            <text>You can enable the Jakarta MVC specific data binding by adding a @MvcBinding annotation to the corresponding controller field or method parameter</text>
        </assertion>
        <assertion id="all-binding-annotations">
            <text>Therefore, Jakarta MVC implementations MUST support @MvcBinding with all Jakarta RESTful Web Services binding annotations</text>
        </assertion>
    </section>
    <section id="error_handling_bindingresult" title="Error handling with BindingResult" level="2" xmlns="">
        <!-- 3.3 - ERROR_HANDLING_BINDINGRESULT -->
        <assertion id="invoke-controller">
            <text>A Jakarta MVC implementation is required to invoke the matched controller method even if binding or validation errors occurred</text>
        </assertion>
        <assertion id="inject-binding-result">
            <text>Controllers can inject a request-scoped instance of BindingResult to access details about potential data binding errors</text>
        </assertion>
    </section>
    <section id="converting_parameters" title="Converting to Java types" level="2" xmlns="">
        <!-- 3.4 - CONVERTING_PARAMETERS -->
    </section>
    <section id="numeric_types" title="Numeric types" level="3" xmlns="">
        <!-- 3.4.1 - NUMERIC_TYPES -->
        <assertion id="convert-numeric">
            <text>When converting values to these numeric Java types, Jakarta MVC implementations MUST use the current request locale for parsing non-empty strings</text>
        </assertion>
        <assertion id="convert-empty-numeric">
            <text>Empty strings are either converted to null or to the default value of the corresponding primitive data type</text>
        </assertion>
    </section>
    <section id="boolean_type" title="Boolean type" level="3" xmlns="">
        <!-- 3.4.2 - BOOLEAN_TYPE -->
        <assertion id="convert-boolean">
            <text>When a Jakarta 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</text>
        </assertion>
        <assertion id="convert-empty-boolean">
            <text>Empty strings are converted to false in case of the primitive boolean type and to null for the wrapper type</text>
        </assertion>
    </section>
    <section id="other_types" title="Other types" level="3" xmlns="">
        <!-- 3.4.3 - OTHER_TYPES -->
    </section>
    <section id="security" title="Security" level="1" xmlns="">
        <!-- 4 - SECURITY -->
    </section>
    <section id="security_introduction" title="Introduction" level="2" xmlns="">
        <!-- 4.1 - SECURITY_INTRODUCTION -->
    </section>
    <section id="cross-site-request-forgery" title="Cross-site Request Forgery" level="2" xmlns="">
        <!-- 4.2 - CROSS_SITE_REQUEST_FORGERY -->
        <assertion id="csrf-obj">
            <text>The Csrf object is available to applications via the injectable MvcContext type or in Jakarta Expression Language as mvc.csrf</text>
        </assertion>
        <assertion id="csrf-hidden-field">
            <text>Applications may use the Csrf object to inject a hidden field in a form that can be validated upon submission</text>
        </assertion>
        <assertion id="csrf-verify">
            <text>Jakarta 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</text>
        </assertion>
        <assertion id="csrf-opt-default">
            <text>The default value of this property is CsrfOptions.EXPLICIT</text>
        </assertion>
        <assertion id="csrf-inject-header">
            <text>Any other value than CsrfOptions.OFF will automatically inject a CSRF token as an HTTP header</text>
        </assertion>
        <assertion id="csrf-custom-header-name">
            <text>The actual name of the header can be configured via the Csrf.CSRF_HEADER_NAME configuration property</text>
        </assertion>
        <assertion id="csrf-default-header-name">
            <text>The default name of the header is Csrf.DEFAULT_CSRF_HEADER_NAME</text>
        </assertion>
        <assertion id="csrf-implicit">
            <text>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</text>
        </assertion>
        <assertion id="csrf-explict">
            <text>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</text>
        </assertion>
        <assertion id="csrf-mediatype">
            <text>Jakarta MVC implementations are required to support CSRF validation of tokens for controllers annotated with @POST and consuming the media type x-www-form-urlencoded</text>
        </assertion>
        <assertion id="csrf-exception">
            <text>The Jakarta MVC implementation MUST throw a javax.mvc.security.CsrfValidationException</text>
        </assertion>
        <assertion id="csrf-default-mapper">
            <text>The implementation MUST provide a default exception mapper for this exception which handles it by responding with a 403 (Forbidden) status code</text>
        </assertion>
        <assertion id="csrf-custom-mapper">
            <text>Applications MAY provide a custom exception mapper for CsrfValidationException to change this default behavior</text>
        </assertion>
    </section>
    <section id="cross-site-scripting" title="Cross-site Scripting" level="2" xmlns="">
        <!-- 4.3 - CROSS_SITE_SCRIPTING -->
        <assertion id="xss-encoders-obj">
            <text>Jakarta MVC applications can gain access to encoders through the MvcContext object</text>
        </assertion>
        <assertion id="xss-escaping">
            <text>The methods defined by javax.mvc.security.Encoders can be used by applications to contextually encode data in an attempt to prevent XSS attacks</text>
        </assertion>
    </section>
    <section id="events" title="Events" level="1" xmlns="">
        <!-- 5 - EVENTS -->
    </section>
    <section id="observers" title="Observers" level="2" xmlns="">
        <!-- 5.1 - OBSERVERS -->
        <assertion id="before-after-controller">
            <text>The events BeforeControllerEvent and AfterControllerEvent are fired around the invocation of a controller</text>
        </assertion>
        <assertion id="after-controller-exception">
            <text>Please note that AfterControllerEvent is always fired, even if the controller fails with an exception</text>
        </assertion>
        <assertion id="before-after-view">
            <text>The events BeforeProcessViewEvent and AfterProcessViewEvent are fired around this call</text>
        </assertion>
        <assertion id="after-view-exception">
            <text>Please note that AfterProcessViewEvent is always fired, even if the view engine fails with an exception</text>
        </assertion>
        <assertion id="redirect-event">
            <text>The last event supported by Jakarta MVC is ControllerRedirectEvent, which is fired just before the Jakarta MVC implementation returns a redirect status code</text>
        </assertion>
        <assertion id="redirect-after-controller-event">
            <text>Please note that this event MUST be fired after AfterControllerEvent</text>
        </assertion>
    </section>
    <section id="applications" title="Applications" level="1" xmlns="">
        <!-- 6 - APPLICATIONS -->
    </section>
    <section id="mvc_applications" title="MVC Applications" level="2" xmlns="">
        <!-- 6.1 - MVC_APPLICATIONS -->
        <assertion id="application-class">
            <text>The controllers and providers that make up an application are configured via an application-supplied subclass of Application from Jakarta RESTful Web Services</text>
        </assertion>
        <assertion id="url-space">
            <text>The path in the application's URL space in which Jakarta 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</text>
        </assertion>
    </section>
    <section id="mvc_context" title="MVC Context" level="2" xmlns="">
        <!-- 6.2 - MVC_CONTEXT -->
        <assertion id="injection">
            <text>MVC applications can inject an instance of MvcContext to access configuration, security and path-related information</text>
        </assertion>
        <assertion id="request-scope">
            <text>Instances of MvcContext are provided by implementations and are always in request scope</text>
        </assertion>
        <assertion id="el-access">
            <text>For convenience, the MvcContext instance is also available using the name mvc in EL</text>
        </assertion>
    </section>
    <section id="providers_in_mvc" title="Providers in MVC" level="2" xmlns="">
        <!-- 6.3 - PROVIDERS_IN_MVC -->
    </section>
    <section id="annotation_inheritance" title="Annotation Inheritance" level="2" xmlns="">
        <!-- 6.4 - ANNOTATION_INHERITANCE -->
        <assertion id="inheritance">
            <text>Such annotations are inherited by a corresponding sub-class or implementation class method provided that the method does not have any Jakarta MVC or Jakarta RESTful Web Services annotations of its own</text>
        </assertion>
        <assertion id="class-vs-iface">
            <text>Annotations on a super-class take precedence over those on an implemented interface</text>
        </assertion>
    </section>
    <section id="configuration_in_mvc" title="Configuration in MVC" level="2" xmlns="">
        <!-- 6.5 - CONFIGURATION_IN_MVC -->
    </section>
    <section id="view_engines" title="View Engines" level="1" xmlns="">
        <!-- 7 - VIEW_ENGINES -->
    </section>
    <section id="view_engines_introduction" title="Introduction" level="2" xmlns="">
        <!-- 7.1 - VIEW_ENGINES_INTRODUCTION -->
        <assertion id="jsp-facelets">
            <text>Implementations MUST provide built-in support for Jakarta Server Pages and Facelets view engines</text>
        </assertion>
        <assertion id="cdi-discovery">
            <text>Namely, any Jakarta Contexts and Dependency Injection 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</text>
        </assertion>
    </section>
    <section id="selection_algorithm" title="Selection Algorithm" level="2" xmlns="">
        <!-- 7.2 - SELECTION_ALGORITHM -->
        <assertion id="selection-algo">
            <text>Implementations should perform the following steps while trying to find a suitable view engine for a view</text>
        </assertion>
        <assertion id="models-binding">
            <text>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)</text>
        </assertion>
        <assertion id="path-relative">
            <text>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/</text>
        </assertion>
        <assertion id="path-absolute">
            <text>If the path is absolute, no further processing is required</text>
        </assertion>
    </section>
    <section id="faces_servlet" title="FacesServlet" level="2" xmlns="">
        <!-- 7.3 - FACES_SERVLET -->
    </section>
    <section id="i18n" title="Internationalization" level="1" xmlns="">
        <!-- 8 - I18N -->
    </section>
    <section id="i18n_introduction" title="Introduction" level="2" xmlns="">
        <!-- 8.1 - I18N_INTRODUCTION -->
        <assertion id="mvc-context-locale">
            <text>The request locale is available from MvcContext and can be used by controllers, view engines and other components</text>
        </assertion>
    </section>
    <section id="i18n_resolving_algorithm" title="Resolving Algorithm" level="2" xmlns="">
        <!-- 8.2 - I18N_RESOLVING_ALGORITHM -->
        <assertion id="resolver-discovery">
            <text>Every Jakarta Contexts and Dependency Injection bean implementing the LocaleResolver interface and visible to the application participates in the locale resolving algorithm</text>
        </assertion>
        <assertion id="resolve-algorithm">
            <text>Implementations MUST use the following algorithm to resolve the request locale for each request</text>
        </assertion>
    </section>
    <section id="i18n_default_resolver" title="Default Locale Resolver" level="2" xmlns="">
        <!-- 8.3 - I18N_DEFAULT_RESOLVER -->
        <assertion id="default-locale-resolver">
            <text>Every Jakarta MVC implementation MUST provide a default locale resolver with a priority of 0 which resolves the request locale according to the following algorithm</text>
        </assertion>
    </section>
</specification>
