Jaxrs-api: Spec: Todo

[mkarg]

This issue serves as an aggregated placeholder for the open TODOs with the Spec document, so we can organize to work in parallel without solving problems twice. The following list shows the open issues. If you like to provide a solution for one of these issues, please post a comment below.

• [x] (@chkal: #801) Initial contribution of the spec asciidoc "as-is" to master
• [x] (@mkarg: #801) URL fixes
• [x] (@mkarg: #801) Maven Coordinates
• [x] (@mkarg: #806) Java EE -> Jakarta EE
• [x] (@mkarg: #802) Can also build spec on JDK 9 and later now
• [x] (@mkarg: #802) Travis CI/CD builds spec
• [x] (@mkarg: #806) 2.x -> 2.2-SNAPSHOT
• [x] (@mkarg: #808) POM Cleanup. Maybe drop assembly?
• [x] (@mkarg: #806) Changes mentioned in CQ 20980: During our initial review of this submission, we noted that the source code headers are either incorrect or missing. As this is a housekeeping issue only, you may proceed with checkin, however we would ask that the correct copyright and license headers be added to the files per Eclipse standards. Please ensure that this is done and notify us via the CQ once this is completed. -- @ivargrimstad triggered @waynebeaton to provide the wanted copyright header template.
• [x] (@mkarg: #808) Publish nightly build of snapshot PDFs/HTMLs Waiting for PMC answer regarding target location
• [ ] (@mcserra: #806, @chkal #883) Modifying references to the JCP with corresponding Eclipse processes.
  
  
  
  • [x] #806 - Everything excluding Activation and JAX-WS
  
  
  • [ ] #883 - JAX-WS
  
  
• [x] (@thadumi: #848) What do we do with references to JSRs? [EJB] Use spec. Name and version number of the specification instead.
• [ ] (@edwin-amoakwa: TBA) References to existing Java EE technologies, acronyms, and JSRs are okay as long as they are properly attributed.
• [x] Be careful not to modify the semantics or behavior — we need Jakarta EE 8 to be functionally equivalent to Java EE 8.
• [x] (@mkarg: #806) Use the original Java EE specification as a guide for your expected end result. Look at the TOC, the figures, the tables, the indentations, etc. The Jakarta EE specification should look very similar to the Java EE counterpart.
• [x] (@mkarg: #806) Continue to use the general template and format that the skeletal specifications are using. For example, use a top-level asciidoc file that defines the overall configuration parameters and includes the other sections of the specification document. The front page, table of contents, and license should all be very similar to the skeletal specifications that were approved for Jakarta EE 8.
• [x] (@mkarg: #807) Split up huge asciidoc into chapters. For most skeletal specifications, the “scope.adoc” file should be replaced with the newly contributed asciidoc version of the specification. Consider breaking down this specification asciidoc file into individual chapter sections if it’s large and you expect multiple people to contribute to this effort. The Platform and Web Profile Specifications are examples of this content break down. Look at Platform.adoc and/or WebProfile.adoc.
• [x] (@mkarg: #806) Remove Oracle Copyright statements. They should be replaced with “Copyright © 2019 Eclipse Foundation” (per the skeletal specification).
• [x] (@mkarg: N/A - apparently already correct) All internal document linkrefs need to be re-worked.
  
  
  
  • Original:
    
    link:WebProfile.html#a43[See Required Components].
  
  
  • Updated:
    
    <<a43, Required Components>>.
  
  
  • Suggest using regedit replacement macros if you have many to change. If just a few, then manual edits are fine.
  
  
• [x] (@mkarg: N/A -- apparently already correct) The links need to be on a separate line from the headings.
  
  
  
  • Original:
    
    == [[a2845]]Interoperability
  
  
  • Updated:
  
  

  [[a2845]]
    == Interoperability

• Again, using regedit replacement macros makes this type of change easier if you have many to change.
  
  
  
  • [x] (@thomasvitale: #813) Use “https://” instead of “http://” for any external links.
  
  
  • [ ] (@chkal: #883) Ensure that external specification links are now pointing at the respective Jakarta EE Specification page (and not the Java EE specifications). ™ does not work for ™ ; use “(tm)”. See more about textual symbol replacements.
  
  
  • [x] (@mkarg: N/A - already just three levels) Sub sections of document beyond three indentation levels (1.2.3) didn’t format very nicely. You may need to visually ensure that the proper indentation levels match up with the original specification expectations. Limit the TOC to three levels (:toclevels: 3)
  
  
  • [x] (@mkarg: N/A - apparently already correct) Inserting images has a different syntax:
  
  
• Original:
  Jakarta EE Application Life Cycle image:Platform_Spec-10.png[image]
• Updated:
  .Jakarta EE Application Life Cycle (note the leading period) image::Platform_Spec-10.png[]
  
  
  
  • [x] (@mkarg: N/A - apparently already correct) Tables didn’t migrate well at all… When you find a table, start off with this type of header and then insert the data on each new line. Here’s an example…
  
  

[[a3318]]
[cols=3, options=header]
.Deployment Descriptor Processing Requirements
|===
|Deployment descriptor
|metadata-complete?
|process annotations?

|application-client_1_2
|N/A
|No
|=== 

• [x] (@mkarg: N/A - already used) [appendix] is a handy element if your specification had them in the past
• [x] (@mkarg: N/A - looks good as-is) Footnotes were kind of ugly. Getting footnotes to render in a similar manner for both pdf and html generation was tricky. I ended up using the following syntax:
• footnote:[text of footnote]  — get text from the [.footnoteNumber] items
• Remove all of the “[.footnoteNumber]…​” items from the migrated document. They are no longer needed.

• Add a dividing line at the bottom of each page where footnotes will reside via three single backward quotes (`). Reference this PR for an example.

• [x] (@mkarg: #806) Formatting code blocks needs work as well. Surround code block in ---- (4 dashes). Add [source, java] or [source, xml] as needed. More specific detailed help can be found in this PR

• [x] (@chkal: #880) Bug: Resource matching: algorithm looks rather weirdly formatted

• [x] (@ThomasVitale: #814) Bug: "Filters and Interceptors / Introduction": There are four... and then there are commas without words. Same at "Filters": " ...namely:... and then there are commas without text.

• [x] (@mkarg: #808) Enhancement: Fail build on error.

Tip: The Asciidoctor Editor plug-in provides a solid set of tools for authoring Asciidoc files in the Eclipse IDE; versions of this plug-in exist for other IDEs as well.

Thanks to @chkal and @ivargrimstad (https://github.com/jakartaee/specification-committee/blob/master/steps_javaee_to_jakartaee.adoc) for their issue lists! :-)

[mkarg]

@chkal Self-service spec assignment roster is opened hereby. ;-)

[mkarg]

WARNING The huge asciidoc file was split into single file per chapter in PR #806. That PR is not merged into master yet. So before starting to work on the spec, please always:

• fetch PR #806
• rebase ontop of the chapter splitup, or cherry-pick the two chapter-split commits.

Otherwise you will have big trouble when pushing your changes due to lots of conflicts!

[ThomasVitale]

Hello @mkarg, I would like to work on the item: Use “https://” instead of “http://” for any external links.

[mkarg]

Hello @mkarg, I would like to work on the item: Use “https://” instead of “http://” for any external links.

Thanks for your kind help. Please also check that the replaced links actually do support https. :-)

[ThomasVitale]

I will, thanks @mkarg. Should I create a separate issue for the task?

[mkarg]

I will, thanks @mkarg. Should I create a separate issue for the task?

Please do not open a separate issue for that but a draft PR. Thanks. :-)

[ThomasVitale]

@mkarg I can also work on "Bug: "Filters and Interceptors / Introduction": There are four... and then there are commas without words. Same at "Filters": " ...namely:... and then there are commas without text."

[mkarg]

@mkarg I can also work on "Bug: "Filters and Interceptors / Introduction": There are four... and then there are commas without words. Same at "Filters": " ...namely:... and then there are commas without text."

@ThomasVitale With "I can also work on" you mean I shall reserve that item for you, right?

[ThomasVitale]

@mkarg Yes, thanks. I got some time and opened a PR for that item: https://github.com/eclipse-ee4j/jaxrs-api/pull/814

[mkarg]

@ThomasVitale Thanks a lot for your kind help! Just to optimize our workflow: (1) Please register for the items first before starting work, so nobody works on the same issue at the same time. (2) Please collect your work in just one PR, it makes the review process quicker, as we need lots of votes otherwise. Thanks. :-) (No, please do not close your existing PRs as a reaction, it was just a tip for the future).

[ThomasVitale]

I will make sure to follow that process in the future, thanks @mkarg

[mcserra]

Hello @mkarg, I would like to work on "Modifying references to the JCP with corresponding Eclipse processes.". Can you save it for me? Thanks

[mkarg]

Hello @mkarg, I would like to work on "Modifying references to the JCP with corresponding Eclipse processes.". Can you save it for me? Thanks

Registered. :-)

[mcserra]

Hey @mkarg, I have some doubts about the task. Can I reach you on your email? Thanks

[chkal]

@mcserra I guess it makes more sense that you ask your question here so that anyone can read it and reply to it.

[mcserra]

Ok, sure. I'm just looking at the documentation, and I see some JCP related links in the bibliography. Is this what is supposed to change? As an example, there is this one:

9 R. Chinnici, M. Hadley, and R. Mordani. Java API for XML Web Services. JSR, JCP, August 2005. See http://jcp.org/en/jsr/detail?id=224.

Is it supposed to change the reference the eclipse project? https://projects.eclipse.org/projects/ee4j.jaxws

[mkarg]

Ok, sure. I'm just looking at the documentation, and I see some JCP related links in the bibliography. Is this what is supposed to change? As an example, there is this one:
9 R. Chinnici, M. Hadley, and R. Mordani. Java API for XML Web Services. JSR, JCP, August 2005. See http://jcp.org/en/jsr/detail?id=224.
Is it supposed to change the reference the eclipse project? https://projects.eclipse.org/projects/ee4j.jaxws

@ivargrimstad As this item is part of your checklist, can you please elaborate?

[chkal]

My guess is that we have to change these references to point to the corresponding Jakarta EE specifications. This is how it was done for the Platform Specification

https://jakarta.ee/specifications/platform/8/platform-spec-8.html#relateddocs

[spericas]

My guess is that we have to change these references to point to the corresponding Jakarta EE specifications. This is how it was done for the Platform Specification

https://jakarta.ee/specifications/platform/8/platform-spec-8.html#relateddocs

I think so. I'll have that change ready shortly.

[spericas]

Does anyone know of any _standard text_ to add for this attribution? "References to existing Java EE technologies, acronyms, and JSRs are okay as long as they are properly attributed."

[mkarg]

All, please update the above checklist with recently merged contributions. Thanks.

[thadumi]

@mkarg I think my task was done with #848, wasn't it?
I can't update the checklist by myself.

[edwin-amoakwa]

Concerning
References to existing Java EE technologies, acronyms, and JSRs are okay as long as they are properly attributed
I have reviewed the spec doc a couple of times and at this point, I don't see any reference of existing Java EE technologies, acronyms, and JSRs. So I propose we check it as done.

The only JavaEE reference is the XML schema which looks like this
<web-app version="3.0" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"> <servlet> <servlet-name>jakarta.ws.rs.core.Application</servlet-name> </servlet> <servlet-mapping> <servlet-name>jakarta.ws.rs.core.Application</servlet-name> <url-pattern>/myresources/*</url-pattern> </servlet-mapping> </web-app>

Ref https://github.com/eclipse-ee4j/jaxrs-api/blob/master/jaxrs-spec/src/main/asciidoc/chapters/applications/_publication.adoc

Any idea if the servlet team has made any changes, that we should effect in the spec doc ?. I checked https://jakarta.ee/schemas/ but couldn't find anything.

Is there any todo regarding this or we leave it as-it-is for now ?

[andymc12]

We do have several places in the spec document that says "JAX-RS". These either need to be attributed to Oracle or replaced with "Jakarta RESTful Web Services". I was thinking of opening a new issue for that discussion and (eventual) action, but maybe we could just use this issue for that?

[edwin-amoakwa]

We do have several places in the spec document that says "JAX-RS". These either need to be attributed to Oracle or replaced with "Jakarta RESTful Web Services". I was thinking of opening a new issue for that discussion and (eventual) action, but maybe we could just use this issue for that?

I think replacing "JAX-RS" with "Jakarta RESTful Web Services" seems more appropriate. When there is consensus on this, I will proceed and effect the changes. Will wait for further comments then take the consensus action.

[mkarg]

We do have several places in the spec document that says "JAX-RS". These either need to be attributed to Oracle or replaced with "Jakarta RESTful Web Services". I was thinking of opening a new issue for that discussion and (eventual) action, but maybe we could just use this issue for that?

I think replacing "JAX-RS" with "Jakarta RESTful Web Services" seems more appropriate. When there is consensus on this, I will proceed and effect the changes. Will wait for further comments then take the consensus action.

There is NO such consensus. Some of us want to get rid of the word "JAX-RS", others do not. Oracle's lawyers confirmed to me that "JAX-RS" never was a trademark of Oracle and that we MAY keep using it WITHOUT any attributation to Oracle. If you ask me, let's keep it "JAX-RS" wherever it makes sense to have an abbreviation, and replace it, where a long form is beneficial.

[edwin-amoakwa]

We do have several places in the spec document that says "JAX-RS". These either need to be attributed to Oracle or replaced with "Jakarta RESTful Web Services". I was thinking of opening a new issue for that discussion and (eventual) action, but maybe we could just use this issue for that?

I think replacing "JAX-RS" with "Jakarta RESTful Web Services" seems more appropriate. When there is consensus on this, I will proceed and effect the changes. Will wait for further comments then take the consensus action.

There is NO such consensus. Some of us want to get rid of the word "JAX-RS", others do not. Oracle's lawyers confirmed to me that "JAX-RS" never was a trademark of Oracle and that we MAY keep using it WITHOUT any attributation to Oracle. If you ask me, let's keep it "JAX-RS" wherever it makes sense to have an abbreviation, and replace it, where a long form is beneficial.

@mkarg Great. Let's leave it as such for the meantime then.
By the way, I didn't say there is a consensus to replace it, that's why I used the word "when". I was saying that because of the comment of @andymc12

[oliviercailloux]

Are you planning to release the specs as an html document somewhere on the web, perhaps, when these TODO will be done? It is nice to be able to refer to specific sections by URL in an electronic discussion, which the PDF documents of Oracle do not permit.

Am I correct that the latest spec document that is available on the web for JAX-RS (thus excluding cloning this repository and building the asciidoc locally) is still the “Version 2.1 Final Release, July 13, 2017” from JSR 370?

[chkal]

@oliviercailloux You can find the latest versions of the spec document (both in PDF and HTML format) here:

https://jakarta.ee/specifications/restful-ws/

This page currently contains the document of Jakarta RESTful Web Services 2.1 (2019) and the latest milestone of Jakarta RESTful Web Services 3.0.

[arjantijms]

@chkal and now it contains the final version here: https://jakarta.ee/specifications/restful-ws/3.0/ ;)

[arjantijms]

I still see a few list items open here, but 3.0 has been delivered. Retargeting this to 3.1 now.

Alternatively, move this back to 3.0 and create a new issue for the remaining items.

[mkarg]

I'm fine with moving it to 3.1