jakartaee / mvc Goto Github PK

Jakarta MVC Specification

Home Page: https://projects.eclipse.org/projects/ee4j.mvc

License: Eclipse Public License 2.0

Shell 0.58% Java 85.28% XSLT 14.14%

mvc's Introduction

Jakarta MVC Specification and API

This project contains the specification document and Java API sources. The project is organized into two modules: api and spec. The api module contains the Java API sources, which may be used to generate the API JAR and JavaDoc. The spec module contains the specification document sources, which may be used to generate the specification document.

Generating the API and JavaDoc

Just enter mvn clean install at the command line. Maven will generate the following artifacts.

API Jar::

The jar containing the api interfaces and classes.
In the directory: /api/target

API JavaDoc::

The JavaDoc for the api interfaces and classes.
In the directory: api/target/apidocs

Generating the Specification

run mvn clean install in the spec directory

The PDF and HTML will be generated in spec/target/generated-docs/

Tagging phrases for the TCK

The Jakarta MVC TCK is a suite of unit tests for validating the compliance of MVC implementations with the specification.

The tests of the TCK are based on assertions representing sentences and phrases in this specification. Labels on specific text elements of the specification are used to mark those which should lead to an assertion in the TCK. The following values are allowed:

tck-testable: The tagged element must be represented by a testable assertion in the TCK
tck-not-testable: The tagged element must be represented by a non-testable assertion in the TCK (e.g. assertions regarding thread safety)
tck-ignore: The tagged element must be excluded when creating a TCK assertion for an outer element. Can be used to exlude explanatory phrases contained in an element marked as tck-testable.
tck-needs-update: The tagged element must be marked with a note in the TCK audit file saying that the tests for this assertion need to be updated, e.g. due to a spec update. Can be used together with tck-testable and tck-not-testable: [tck-testable tck-needs-update]#Some sentence...#.
tck-id-SOME_ID: This tag defines an ID that has to be used to reference this particular assertion in the TCK. SOME_ID can be any text, number or special character- anything up to the next space " " or closing bracket ] will be taken as the ID. Can be used together with tck-testable: [tck-testable tck-id-http://some.issue.tracker/url]#Some sentence...#. tck-testable without a defined id will get a letter assigned as their ID, in the order of apperance within their section (a, b, c, ...)

Audit XML to calculate spec coverage in tests

mvn clean install (or just mvn generate-resources) in the spec directory will create a tck-audit.xml file under target/generated-docs. This file contains the [tck-testable] assertions found in the spec (asciidoc), and is used in the TCK project to analyse the spec coverage in tests.

The process is copied and adapted from the beanvalidation spec project (https://github.com/eclipse-ee4j/beanvalidation-api).

mvc's People

Contributors

Stargazers

Watchers

Forkers

ivargrimstad daniel-dos roanbrasil lefloh chkal seanpm2001 elite2012

mvc's Issues

Create PR for 2.1 Release Review

Create PR for 3.0 Plan Review

Support sub-resource locators

I have a highly dynamic application which makes use of JAX-RS sub-resource locators. Unfortunately, those are not supported by default with MVC.

I could work around this limitation with a custom interceptor on my locator method (@ControllerLocator) which intercepts the result of the method and decorates the sub-resource with an InterceptionFactory to apply the interceptors needed for @Controller to work. This workaround depends on vendor-specific (krazo) classes like AroundController and ValidationInterceptorBinding. If the interceptors had been bound to @Controller (which could be turned into an InterceptorBinding via BeforeBeanDiscovery.addQualifier()) instead of specific annotations then it could have been implemented without relying on krazo classes.

Completion Steps for MVC 1.1

Specification Committee Member...

creates an issue in the specification project that includes the following checklist for the specification project team:

MVC Specification Project Team...

promotes api staging release promotes the specification api jars to maven central. An example release job script can be found here https://wiki.eclipse.org/MavenReleaseScript.
go through the merged jakarta.ee specification website page to verify all the links are valid.
approve the compatibility request.
The compatible implementation project/vendor MUST send an email to [email protected] for approval of the compatible implementation for trademark usage.
merge any final release branch as appropriate for the branch management for the project.

Is there a reason why @MvcBinding cannot be used at class level?

Issue by mscharhag
Saturday May 26, 2018 at 15:08 GMT
Originally opened as mvc-spec/mvc-spec#161

Hello,

I am wondering why @MvcBinding can only be used on fields, methods and parameters. (Probably because JAX-RS binding annotations can only be used on this types?)

Annotating all fields of a JAX-RS bean parameter with @MvcBinding looks way more common to me than annotating some fields and some not. Wouldn't it be convenient if a class could be annotated with @MvcBinding instead of annotating each field separately?

Maybe I am missing something here?

Specify Partials as Views

Prosed syntax:
<filename>::<elementId>

Example: Add a row to a table in the view

Compatibility Certification Request for Eclipse Krazo 2.0.1

Add module-info

Follow the conventions published by the Jakarta EE Platform project

https://github.com/eclipse-ee4j/jakartaee-platform/wiki/Modularized-Jars

Create Release Record for 2.1

Compatibility certification request for Eclipse Krazo 1.1.0

Compatibility Certification Request for Eclipse GlassFish 6.2.0

Organization Name ("Organization") and, if applicable, URL:
Eclipse Foundation
Product Name, Version and download URL (if applicable):
Eclipse GlassFish 6.2.0
Specification Name, Version and download URL:
Jakarta MVC 2.0
TCK Version, digital SHA-256 fingerprint and download URL:
Jakarta MVC TCK 2.0.0
SHA-256: 27a09b18169e46571898375d2eb1d05000301828c5d16dfc5d56e882690d55ed
Public URL of TCK Results Summary:
https://glassfish.org/certifications/jakarta-mvc/2.0/TCK-Results-6.2.0
Any Additional Specification Certification Requirements:
None
Java runtime used to run the implementation:

openjdk version "11.0.11" 2021-04-20
OpenJDK Runtime Environment AdoptOpenJDK-11.0.11+9 (build 11.0.11+9)
OpenJDK 64-Bit Server VM AdoptOpenJDK-11.0.11+9 (build 11.0.11+9, mixed mode)

Summary of the information for the certification environment, operating system, cloud, ...:
Linux basic-7b0jn 5.12.7-300.fc34.x86_64 #1 SMP Wed May 26 12:58:58 UTC 2021 x86_64 GNU/Linux
By checking this box I acknowledge that the Organization I represent accepts the terms of the EFTL.
By checking this box I attest that all TCK requirements have been met, including any compatibility rules.

Access javax.ws.rs.core.UriInfo.getAbsolutePath() in views

Is it possible to get the value of javax.ws.rs.core.UriInfo.getAbsolutePath() of the current request in a view (e.g. a JSP page)? A typical use case would be to style a navigation link differently if the request URI matches the link URI.

It would be nice to be able to do something like this:

<nav>
    <a class="${mvc.requestUri eq mvc.uri('MyController#home') ? 'active' : ''}" href="${mvc.uri('MyController#home')}">Home</a>
</nav>

Update the Specification Document

Chapters

Create PR for 2.0 Release Review

Create PR for 2.0 Plan Review

Compatibility Certification Request for Eclipse GlassFish 7.0.0-M9

Support for HTTP forward

Issue by mvcbot
Tuesday Jan 13, 2015 at 18:01 GMT
Originally opened as mvc-spec/mvc-spec#35

Original issue MVC_SPEC-23 created by Santiago Pericas-Geertsen:

JAX-RS 2.1 is likely to support a redirect call (just like servlet). This issue is recorded to track if whatever support is added to JAX-RS is sufficient for MVC.

Why is CSRF protection explicit by default?

Since a while I ask myself, why the specification defines explicit CSRF protection as a default instead of the implicit one.

From a security point of view, IMO every web application should use CSRF protection by default, because nobody wants an per default enabled attack point. I think, the specification should help users to build secure web applications and let them think about what they are doing, in case they really want to disable this security feature.

Would be great to get an explanation for this design decision :)

Field injection for binding is a mistake

Issue by graemerocher
Wednesday Nov 14, 2018 at 14:01 GMT
Originally opened as mvc-spec/mvc-spec#206

Reading the spec, it seems that the pattern that is encouraged is this:

@Inject
    private User user;

    @GET
    @Controller
    public String hello(@QueryParam("name") String name) {
        user.setName(name);
        return "hello.jsp";
    }

IMO this is a mistake looking to the future. There are several problems with this:

Thread safety if the controller is singleton. The controller would not automatically be thread safe, which would force the introduction of proxies that use request scope/ thread local, which impacts performance and memory consumption
Requirement for reflection - frameworks would be required to use reflection to inject User user using a field based approach only

Fields should be used for dependency injected components and not the model. It would be better written as:

    @GET
    @Controller
    public String hello(@Model User user, @QueryParam("name") String name) {
        user.setName(name);
        return "hello.jsp";
    }

This has the advantages:

Reflection would not necessary be required (for example in Micronaut)
There are no thread safety concerns with singleton/application scoped controllers.

This also aligns closer with how the most popular MVC (Spring MVC) works.

Relates to #16

Upgrade APIs to EE 10 versions

Jakarta MVC 2.1 targets Jakarta EE 10, so we need to adapt the APIs we use.

Support View annotation on Controller methods returning non void types (except Viewable)

Issue by mvcbot
Friday Aug 07, 2015 at 10:04 GMT
Originally opened as mvc-spec/mvc-spec#63

Original issue MVC_SPEC-51 created by beryozkin_sergey:

@Controller
@View("book.jsp")
public Book getBook() {}
{code}

I.e, if it is non-void, non-Viewable response with View then the response is treated as the content to be processed by the view engine.
 
The simplest and safe way to bind Book to HTTP request attribute is to assume a convention that a class name (Book.class.getName()) is used as a key. 
Additionally (or alternatively) an extra optional attribute can be added to @View:
{code:java}
@Controller
@View(value="book.jsp", name="book")
public Book getBook() {}
{code}

Furthermore the above style can also support:

@Controller
@View("book.jsp")
@Produces({"application/xml", "application/json", "text/html"})
public Book getBook() {}

given that it is very typical in JAX-RS to have a single method with multiple Produces values.

I think this style is very important to support because it is more natural to write than having to use a @nAmed sync such as Greetings in the spec example or dealing with Models directly, in both cases the application directly having to be aware of the MVC semantics.

IMHO it is not difficult to support it at a spec level. It is also another good example why a strict CDI binding requirement may need to be relaxed and limited to a subset of styles.

Support multi ApplicationPaths

If I mixed Jaxrs and MVC in the same application, I hope the application paths can be declared respectively and also allow apply different config(default media type, and external security config etc) on both application paths.

eg.
/api for RESTful APIs.

default media type set to application/json
use jwt stateless auth.

/web for MVC web pages.

default media type is text/html
use a form based login, and enable session for loggined user.

Fix date of copyright in license-efsl.adoc

Create Release Record for 3.0

Create Release Plan

https://projects.eclipse.org/projects/ee4j.mvc/releases/2.0

Support for parameter injection in CDI

Issue by mvcbot
Thursday Oct 16, 2014 at 17:01 GMT
Originally opened as mvc-spec/mvc-spec#16

Original issue MVC_SPEC-4 created by Santiago Pericas-Geertsen:

Data binding in MVC will likely take advantage of injection in general, and parameter in injection in particular. Will CDI.next be able to handle the kind of parameter injection that MVC needs?

Standardize org.eclipse.krazo.defaultViewFileExtension as javax.mvc.engine.defaultViewFileExtension

Issue by ngriffin7a
Thursday May 02, 2019 at 19:32 GMT
Originally opened as mvc-spec/mvc-spec#213

As discussed in a related Google Groups thread, I recommend that the org.eclipse.krazo.defaultViewFileExtension feature be standardized as javax.mvc.engine.defaultViewFileExtension.

Add accessor for form method overwrite field name

Since #72 it is possible to add a hidden form field to overwrite the form's HTTP method. The field's name is customizable, but unfortunately there is no easy access to get the name for e.g. adding it to the form field. So even if the field's name is declared in the Application#getProperties Map as e. g. _hiddenMethod instead of the default _method, the API user needs to add _hiddenMethod to each single hidden input field. This may lead to errors and less user experience.

To avoid the need for this copy-and-paste an additional method, which returns the field's name, in MvcContext would be helpful, e.g. MvcContext#getFormMethodOverwriteParam.

Order of chapters wrong - chapter 9 after Appendix B

It seems there is some error in the order of the Spec's chapters. Chapter 9 occurs after Appendix B. This is wrong and the order must be fixed.

Compatibility Certification Request for Eclipse Krazo 2.0.0

Compatibility Certification Request for Eclipse Krazo for Jersey 3.0.0 (Java 11)

Non-Declarative API

Issue by mvcbot
Monday Jan 05, 2015 at 18:23 GMT
Originally opened as mvc-spec/mvc-spec#25

Original issue MVC_SPEC-13 created by Santiago Pericas-Geertsen:

Consider adding support for a non-declarative API. This is currently not supported by JAX-RS, but may be useful for MVC.

Compatibility Certification Request for Eclipse Krazo for Jersey 3.0.0 (Java 17)

Idea: Standardized way to override HTTP methods in forms

Issue by erdlet
Monday Sep 02, 2019 at 15:14 GMT
Originally opened as mvc-spec/mvc-spec#219

Hi all,

a few months ago, a feature to was added to Krazo which enables developers to override the HTTP method used in HTML forms by setting a hidden field that is evaluated while the request is processed. This way, developers can implement controllers which are using the full power of HTTP verbs what results in clearer and more understandable APIs.

Therefore I wanted to ask what you think about standardizing this functionality in the MVC API to ensure every person using an MVC implementation can profit from it. Also, this is something which nearly all MVC frameworks I know support (e.g. Spring MVC, Rails, Grails, Django) very successfully.

Update Javadoc

#15

Create PR for 2.1 Plan Review

Provide access to parameter type via ParamError

Issue by chkal
Sunday Jul 08, 2018 at 08:41 GMT
Originally opened as mvc-spec/mvc-spec#173

I would be nice to have something like getJavaType() on ParamError. The actual type of the parameter on the Java side is very important, especially in the context of binding errors.

Actually this would be very easy to implement in Ozark for BindingError. But adding support for ValidationError would require quite some work. Therefore, I'm assigning this to "Future".

Move source for mvc-spec.org to this repository

We would need to get GitHub pages set up and convert the source to be able to run here with the jekyll-jakartaee-theme

This will enable us to get the site published on https://mvc.jakarta.ee along with the other specs

Migration to jakartaee GitHub orga?

I recognized that the specs are moving into the jakartaee GitHub orga. Think we shall do it too, @ivargrimstad?

Finalize MVC 2.0 release

Tasks to complete the MVC 2.0 release:

promotes api staging release promotes the specification api jars to maven central. An example release job script can be found here https://wiki.eclipse.org/MavenReleaseScript.
go through the merged jakarta.ee specification website page to verify all the links are valid.
approve the compatibility request.
The compatible implementation project/vendor MUST send an email to [email protected] for approval of the compatible implementation for trademark usage.
merge any final release branch as appropriate for the branch management for the project.

Specify support for Jakarta REST `ExceptionMapper<T>`

I recognized that we're not specifying exception handling in MVC applications or, at least, how the existing approaches shall be used. In my opinion, we should add some section about how MVC implementations should handle the response from jakarta.ws.rs.ext.ExceptionMapper implementations, because at the moment there is the need to use Krazo-specific API (Viewable).

@Provider
@Priority(Interceptor.Priority.APPLICATION + 999)
public class GeneralExceptionMapper implements ExceptionMapper<Exception> {

    @Override
    public Response toResponse(final Exception exception) {
        return Response.serverError().entity(new org.eclipse.krazo.engine.Viewable("serverError.jsp")).build();
    }
}

I think the implementations should ensure, that we can return the same values as in @Controller annotated resources, so we have a consistent and clear behavior. The example posted above would then look like this:

@Provider
@Priority(Interceptor.Priority.APPLICATION + 999)
public class GeneralExceptionMapper implements ExceptionMapper<Exception> {

    @Override
    public Response toResponse(final Exception exception) {
        return Response.serverError().entity("serverError.jsp").build();
    }
}

Please add your feedback or possible Jakarta REST limitations which I'm not aware of.

Compatibility Certification Request for Eclipse Krazo for RESTEasy 3.0.1

Add ability to "opt out" of CsrfOptions.IMPLICIT

Issue by mvcbot
Sunday Oct 25, 2015 at 19:01 GMT
Originally opened as mvc-spec/mvc-spec#70

Original issue MVC_SPEC-58 created by kito75:

It'd be nice to opt out of implicit CSRF protection, maybe with an annotation like @CsrfValidDisabled,

jakarta.mvc-parent
- jakarta.mvc-api
- jakarta.mvc-spec

#14