Closed mbroz2 closed 3 years ago
Charlotte-Holt
commented
3 years ago Hey, @mbroz2 - I think we have an issue for this: #1494. I can close the older one, since this issue has more info, and @lauracowen, @dmuelle, and I can talk about getting it prioritized.
mbroz2
commented
3 years ago Any update on this one?
dmuelle
commented
3 years ago I haven't been able to prioritize it yet. I think we can target for 21.0.0.5 or 21.0.0.6. We don't have dedicated graphics resources at the moment so an illustration will likely take longer.
Would it make sense to target to align with Jarkarta ee9?
mbroz2
commented
3 years ago I think we should have it published no later then that. However, since we've already announced Open Liberty Jakarta EE 9 compatibility in our beta releases, the earlier we can get the document published the better.
dmuelle
commented
3 years ago Hi @mbroz2 , before I work on a draft, just want to make sure I have the proper scope and granularity. Also want to try and put a finer point on what distinguishes OL w/r/t Jakarta EE. The following rough outline is just to sketch out the details. Any text below will be revised and refined
I would place the image here, and then go into the breakdown below.
sum it up and provide links to docs/guides/external for more info
Is that basically what you had in mind? yes, and I made some updates. Also, maybe we should include "IDE" somewhere in here, and how they can help integrate all this for a developer, even abstracting some of the complexity away. Could also expend to cover APIs and SPIs, though, like IDE, those are not explicitly Java topics.
dmuelle
commented
3 years ago also w/r/t a diagram- what should it show? here are a couple napkin sketches as a starting point before I sketch something less insane-looking in AI:
I'm sure I don't have everything is the right place/relation, but are these the pieces we'd want to include? Or something more simple, Just EE with SE and components inside?
mbroz2
commented
3 years ago My thinking on the diagram is that it should show: JVM, JRE, JDK, Java SE, Jakarta EE, Open Liberty, & App. (we could also have have libs under open liberty and/or JRE) So I think you got them all, though I would place the JVM inside the JRE. We may also include JSR if we wanted to, but on the fence; we probably don't want to include FX and ME.
I would not add anything 'external' like DB or clients/services as I think that will complicate things and is not specific to Java.
I like the "create" "execute" and "run" subheadings, but I would put "run" under JRE and either "execute" or perhaps even better "interpret" under JVM
dmuelle
commented
3 years ago Initial draft is now available for review:
https://docs-draft-openlibertyio.mybluemix.net/docs/latest/jakarta-ee.html
dmuelle
commented
3 years ago Hi @tevans78 @jhanders34 ,
Michal suggested the two of you as potential reviewers for this "Jakarta EE Overview" docs topic. He opened this issue for a Jakarta topic in a similar vein to our MicroProfile Overview in the docs. My content proposal, which Michal edited and approved, is in a previous comment. Are either of you able to review this brief overview draft?
https://docs-draft-openlibertyio.mybluemix.net/docs/latest/jakarta-ee.html
tevans78
commented
3 years ago @dmuelle Where would you like review comments to be recorded? The first sentence isn't quite accurate since I would regard a platform to be implementation rather than just the APIs or specs.
tevans78
commented
3 years ago I think that you should ask @kwsutter to review as well ... I'm not sure about the history and the use of certain terms. For example, I think that a JSR was something specific to the JCP process. For Jakarta EE, the JCP was replaced by the JESP - https://jakarta.ee/about/jesp/ - I don't know what the equivalent of a JSR is now.
dmuelle
commented
3 years ago Thanks @tevans78 - any review comments can go in this issues so we we have a running record of comments from different reviewers. There seems a good deal of variation in how things are named/explained across different sources and over time, so hopefully we can find some consensus.
The first sentence isn't quite accurate since I would regard a platform to be implementation rather than just the APIs or specs.
The Jakarta tutorial from Eclipse refers to "the Jakarta EE 9 Platform", the Jakarta EE about page says "We expect the Jakarta EE platform to evolve rapidly,..". But it also says "Jakarta EE is a set of specifications..." Would it be more accurate to avoid calling it a "platform"? And if so, should any distinction be made along those lines between Jakarta and Java SE, which is referred to as a platform?
I think that a JSR was something specific to the JCP process. For Jakarta EE, the JCP was replaced by the JESP - https://jakarta.ee/about/jesp/ - I don't know what the equivalent of a JSR is now.
I'll follow up with Kevin on this as it's not clear from the JESP page what the equivalent of the JSR is for Jakarta
dmuelle
commented
3 years ago HI @kwsutter - are you able to provide review for this Jakarta EE Overview draft for the OL docs? If so, you can leave any review comments in this issue.
https://docs-draft-openlibertyio.mybluemix.net/docs/latest/jakarta-ee.html
Before he went on leave, Michal opened this issue for a Jakarta topic in a similar vein to our MicroProfile Overview in the docs. My content proposal, which Michal edited and approved, is in a previous comment.
One initial question that @tevans78 raises, is whether "JSR" is still a relevant term for Jakarta EE, and if not, is there a functional equivalent? Michal suggested the JSR as one of the terms to cover in this topic. Thanks
mbroz2
commented
3 years ago I'm wondering if we should make the title "Jakarta EE (formerly Java EE)" (but just keep it as-is in the ToC). Otherwise, if we keep it as is (with just "Jakarta EE") then make sure the description/SOE stuff includes Java EE.
I'll leave the "Platform" vs "Set of Specifications" JEE description to @kwsutter
Should we expend first instance of "API"? Maybe even have a sentence on what an API (and SPI) is and how it's used?
"Jakarta EE consists of a superset of Java SE" isn't as accurate as "Jakarta EE extends Java SE" as 'superset' implies that JEE provides what JSE provides, which is not the case (one still needs to provide JSE in order to use JEE, which builds on top of it).
When we talk about JVM, I think we should mention that there are more then one implementations, listing HotSpot and J9 (and mentioning that Open Liberty performs better on J9 and linking to Semeru). Can draw a parallel between JEE and JVM both being specs, and and just like there's different implementers of the JEE spec (like Open Liberty), there's different implantations of the JVM as well (J9).
I'm not sure I like the "Open Liberty" part of the image. I think we should make it smaller, change "cloud native application" to just "app". I also don't think it should be connected to the JRE.... yes the server is the runtime for the app, but the image implies that the server is the JRE.
I'm not sure how we want to illustrate that the Open Liberty server/runtime runs on top of the JRE, and provides the JEE spec implementation for the app to leverage...... but the way we have it now seems like it might be confusing. Maybe we can keep it the same color as JRE (to indicate 'runtime'), but move it so that it's half overlayed on JEE and the other half outside of the diagram?
Also, minor nitpick, the left side of the Java SE box seems unnecessarily wide?
Under "Platform versions": After the talk of longterm support, add a sentence regarding short-term releases and their support, and link to our JSE Support doc: https://docs-draft-openlibertyio.mybluemix.net/docs/21.0.0.9/java-se.html Add a sentence at the end regarding Jakarta 9.1 and that it adds support for Java SE 11 (and no API changes from 9.0)
Overall, looks good and I really like the table you added.
kwsutter
commented
3 years ago Overall, very good. Thanks for getting something like this into the docs!
Second paragraph under Java Platforms. I would move the second sentence about Jakarta EE to the end of the paragraph. It doesn't flow in its current form. The paragraph starts off talking about Java SE, then Jakarta EE, and then back to Java SE. Moving that second sentence would help with the flow.
I'm stumbling a little bit with the diagram, but maybe it's just me. The Open Liberty box seems to imply that it implements portions of the SDK, JRE, and JVM. It doesn't. It definitely relies on these pieces, but it doesn't implement them. Even Java SE is a stretch. But, due to some of the APIs being defined in Java SE (transactions, security, jdbc, etc), I can buy off on that. I don't have any other great ideas for an update. So, just take this as a suggestion and see if any great ideas pop up.
In the Platform Versions section, you could also mention that Jakarta EE 9.1 was produced in 2Q2021 and supports the Java SE 11 runtime.
As @tevans78 pointed out, the term JSR is not in the Jakarta EE vocabulary. So, that first paragraph under Jakarta EE Specifications will need to be re-worked. Instead of JSRs, a new feature is proposed via github Issues which will eventually turn into a Release Plan, which needs to be voted on. A good overview of the process can be found here: https://jakarta.ee/committees/specification/guide/
If you want more detail or more just more references, you could also reference the Jakarta EE Specification Project (JESP, https://jakarta.ee/about/jesp/) which builds upon the Eclipse Foundation Specification Project (EFSP, https://www.eclipse.org/projects/efsp?version=1.2). We also have an Operations Guide which supplements the Specification Process: https://jakarta.ee/committees/specification/operations/. And, since this paragraph also mentions the TCK, here is the defined TCK process: https://jakarta.ee/committees/specification/tckprocess/
One other key point about the ratifying compatible implementation is that it must be "open-source". So, if you stick with your current wording for this paragraph, I would do this: "..process of developing at least one open-source reference implementation.."
In the second paragraph, you mention that Open Liberty is a reference implementation. It was for Jakarta EE 9.1, but that designation is not "forever". Each release of Jakarta EE could have a new set of reference implementations. Also, to be clearer, I would add the following: "..all the required Jakarta EE specifications as defined by the Jakarta EE Platform Specification."
In the table, I would be consistent in the Open Liberty Feature column. The first row just has "cdi", but the other rows spell out the feature name. I would use the short name through out and I would also append the version. Thus, the text would be "cdi-2.0" and the hotlink would take them to the CDI 2.0 html page.
I like the Try It Out column! Nice touch.
In the Jakarta EE and Open Liberty section: First sentence is missing "to": "..goes back to the beginning of the project.."
The Working Group reference is okay, but I think the key group that we're involved with is the Jakarta EE Specification Committee (Dan is primary, I am alternate). This is where the meat of the various releases are defined. The Spec Committee needs to do the voting on the various Release Plans, etc (as outlined in the earlier process documents).
Don't forget to mention Jakarta Batch since we (IBM, Scott Kurz) are leading that effort.
I think that's enough to keep you busy for a bit. :-) FYI, I will be out of the office starting this afternoon and won't be back until the 31st. If you have questions about my comments, you could ask @NottyCode, or @jhanders34, or @tjwatson. Thanks!
dmuelle
commented
3 years ago Thanks so much for reviewing @kwsutter @mbroz2. I've updated the draft per your comments and detailed the changes I made below.
https://draft-openlibertyio.mybluemix.net/docs/latest/jakarta-ee.html
Let me know if you see anything else that needs edits or clarification. Thanks!
mbroz2
commented
3 years ago Looks good, the only thing I would consider tweaking is the structure/flow of these two paragraphs:
All Java platforms provide a set of APIs and a Java virtual machine (JVM), which is a program that interprets Java application code. Like Jakarta EE, the JVM is a specification. Just as different implementations of the Jakarta EE specification are available, such as Open Liberty, different implementations of the JVM specification exist, such as OpenJ9 and HotSpot. Although each of these implementations derives from the same JVM specification, performance differences can occur among them. For example, Open Liberty has a better memory footprint and faster startup time on OpenJ9 than on HotSpot.
Java SE provides the Java Runtime Environment (JRE), which is used to run Java applications; and the Java Software Development Kit (SDK), which is a collection of tools for developing Java applications. The JRE includes the JVM and the Java Class Library (JCL), which is a set of dynamically loadable libraries that the JVM can call at run time. These libraries enable Java applications to be operating-system independent by supplying many common functions that are provided by modern operating systems. Jakarta EE extends Java SE with a collection of APIs that are designed for networked enterprise application development.
As it feels like JVM is talked about half in the first and half in the second, so I think the two JVM parts need to be combined. Maybe something like:
Java SE provides the Java Runtime Environment (JRE), which is used to run Java applications; and the Java Software Development Kit (SDK), which is a collection of tools for developing Java applications. The JRE is primarily composed of the JVM and the Java Class Library (JCL).
The JVM is a program that interprets Java application code. Like Jakarta EE, the JVM is a specification. Just as different implementations of the Jakarta EE specification are available, such as Open Liberty, different implementations of the JVM specification exist, such as OpenJ9 and HotSpot. Although each of these implementations derives from the same JVM specification, performance differences can occur among them. For example, Open Liberty has a better memory footprint and faster startup time on OpenJ9 than on HotSpot. The JCL is a set of dynamically loadable libraries that the JVM can call at run time. These libraries enable Java applications to be operating-system independent by supplying many common functions that are provided by modern operating systems. Jakarta EE extends Java SE with a collection of APIs that are designed for networked enterprise application development.
Also, I feel like we should formally document the tables from "Updating Open Liberty features in server configurations" section in https://openliberty.io/blog/2021/03/17/eclipse-transformer.html, and I wonder if this document would be the right fit (or perhaps the Feature Overview document... or in EE9 convenience feature doc). We could add the tables to the end of the doc, or expand the existing table you have to cover all the features. In other words, having a list of all the Jakarta EE9 features by the spec name, the open liberty feature name, the old EE8 name, and then any links to guides that we might have on the subject.
dmuelle
commented
3 years ago Thanks @mbroz2 - I've updated the draft to reflect your suggestion for the two JVM/JRE/JCL paragraphs:
https://draft-openlibertyio.mybluemix.net/docs/latest/jakarta-ee.html
For the "Updating Open Liberty features in server configurations" info, I've opened an issue for a separate doc (#4626 ). This doc will link to that one once it publishes.
Are any further edits needed for this Jakarta topic? If not, is it ready to publish or should we wait until ~ 20.0.0.11 for the EE9 OL release (and the Updating features... topic)?
mbroz2
commented
3 years ago LGTM, we can wait for GA of EE9.1 support, but there's also not really a good reason to wait until then, which makes me think we should just publish this topic with 21.0.0.10 (since the content is already applicable to not only Jakarta EE 8, but also our betas).
So unless @kwsutter or @jhanders34 have strong feelings otherwise, I would just publish this with the next release
dmuelle
commented
3 years ago @mbroz2 - if you're satisfied with this issue from a technical perspective, can you add the technical reviewed label? I can then get it queued for peer review and ready to publish for 21.0.0.10. Thanks!
ManasiGandhi
commented
3 years ago @dmuelle The topic looks good! A few edit suggestions
[x] The title Jakarta EE sounds generic. As this topic is in Open Liberty, could you make the title more specific to the Open Liberty context, or maybe Jakarta EE overview
[x] The short description needs to mention somewhere that Open Liberty is an implementation of the Jakarta EE specification.
[ ] An API is an interface that allows an application to use specific data or functions of an operating system or another application or service. Is it necessary to define API?
[x] Jakarta EE application servers such as Open Liberty host these containers and provide standardized system services that any application that is developed for Jakarta EE specifications can use. Add commas between servers and such , and Liberty and host.
[x] These open source specifications make applications more portable and resilient and help developers focus on writing applications rather than managing low-level infrastructure details. How do the open source specifications make applications more portable and resilient? It might not be clear to the reader from the information provided here.
[x] They are widely used for enterprise applications in banking, e-commerce, travel, and more. Could you specify who is They ?
-[ ]The other three platforms are Java SE, which provides the core Java functions; Java ME, which provides resources for mobile applications; and JavaFX, which provides graphics and media packages for rich client applications.Acrolinx flags this sentence as too long.
[ ] different implementations of the JVM specification exist, such as OpenJ9 and HotSpot. OpenJ9 links to IBM Semeru Runtime Downloads. Is it where it was intended to link to?
[x] Could you begin this sentence in a new paragraph The JVM is a program that interprets Java application code. just like JCL?
[x] Jakarta EE extends Java SE with a collection of APIs that are designed for networked enterprise application development.could you instead say enterprise network application development ? networked seems to be rarely used elsewhere, but use your discretion.
[x] The following diagram shows the relationship between these components of the Jakarta EE platform. Change to, The following diagram shows the relationship between the components of the Jakarta EE platform. Next sentence says these components.
[x] The primary change in this release was to replace javax with jakarta in Jakarta package names.Could you add nouns after javax and jakarta ?
[ ] Jakarta EE specifications table. Should there be a sentence describing what the table is about?
[ ] In the Functions column of the table, the sentences begin with verbs. Usually we use Specify to begin a sentence, not other words like enables, provides etc. One sentence in the column ends with a period and the rest don't.
[x] Our team is active across the Jakarta Working Group, with Dan Bandera and Kevin Sutter sitting on the Specification Committee and Dan Bandera and Ian Robinson sitting on the Steering Committee.Add comma` Our team is active across the Jakarta Working Group, with Dan Bandera and Kevin Sutter sitting on the Specification Committee, and Dan Bandera and Ian Robinson sitting on the Steering Committee.
[x] We are also taking a leading role in the Jakarta EE Platform umbrella specification. Acrolinx flagsWe .
[x] New versions of Jakarta EE implementing features are regularly introduced in Open Liberty beta releases before they are included in a full GA release.Maybe say general availability (GA) .
`
dmuelle
commented
3 years ago Thanks for reviewing @ManasiGandhi - I have updated the file per your review, with the following exceptions:
Is it necessary to define API?
An earlier reviewer requested a brief definition for API. I agree most readers will already know this but this is a high-level doc so I think it's appropriate.
Acrolinx flags this sentence as too long.
I think it's only being flagged because acrolinx is counting "Java SE" and "Java ME" as two words each instead of one compound noun in both cases
OpenJ9 links to IBM Semeru Runtime Downloads. Is it where it was intended to link to?
This is the intended location per Michals review above. Semeru is our recommended source for J9
Jakarta EE specifications table. Should there be a sentence describing what the table is about?
The two sentences that precede the table describe it
In the Functions column of the table, the sentences begin with verbs. Usually we use Specify to begin a sentence, not other words like enables, provides etc. One sentence in the column ends with a period and the rest don't.
The descriptions are based on the specification definitions. I think adding a generic "This specification specifies.." or similar to each entry would not add value and might make the table less readable. I did remove the period though
https://draft-openlibertyio.mybluemix.net/docs/latest/jakarta-ee.html
dmuelle
commented
3 years ago changes on vNext, doc will publish with 21.0.0.10
I would like to see a doc, similar to our MP Overview doc, perhaps titled something like 'Java/Jakarta EE', which would focus on explaining what Java EE & Jakarta EE is, but before doing so, it would also provide quick overview of what Java SE is (JDK, JRE, JVM), and how it all fits together, and what role Open Liberty plays in that picture.
An illustration that shows how all those pieces fit together (relatively straightforward as these items are largely nested) would be helpful to go along with the text.