Skip to main content

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
Re: [jakartaee-examples-dev] [External] : Re: Volunteering for Jakarta Examples

Hi Andy,

So sorry for the tardy reply.

I like your new format for the FirstCup. Once you are happy with it, submit a PR and I'll merge it for you. I merged a couple of old PRs that I need to merge in first so -- if you can refresh your fork, before you merge that will probably be best.

My outline abut the tutorials and samples doesn't exist anywhere public. The web material for these is pretty messy right now. The history of EE Examples was somewhat spotty. I will provide some text about this in the readme files for all these projects.

I will start a conversation with the forked EE examples repository to see if there is any interest in trying to reconcile and merge these back together. That forked repository might give you some better insight into how to run any of these samples.

The Java SE version that readers will want to use is probably going to be dictated by their App. server. For the EE 9 Spec. requires SE 8 and 11 (if they are going to develop code they'll need the JDK, not just Java SE). Some App. Servers may support newer JDK versions. Speaking from a Java perspective, we'd want to encourage any user to download the latest JDK update that is available but we probably don't want to have to refresh these guides every time there's a new JDK update. So -- I'd encourage the tutorials and samples to say something like: "you should always try using the latest Java <X> update". If we want to list a specific update, I'd put that in the context of "... we tested with Java 8 u144," a footnote, or something along those lines. The current update version of Java SE 8 is u291 so that is quite a bit further down the pike than what we are recommending in the docs. For SE 11, the latest is 11.0.11.

Legacy features of EJB are certainly out of vogue right now but the current EJB specifications and features (EJB 3+) are still actively used by many applications so I doubt that will go away any time soon. As you point out, CDI is certainly more popular but EJB also serves as an entree to persistence -- which was broken out into JPA -- so some combination of CDI and JPA would probably be needed to replace most of EJB -- and then the inter-app. communication features of MDBs would need to find a home someplace. I would expect some additional deprecation work will likely occur. I'd look at the bean managed persistence features as likely headed for the chopping block -- because they are replaced by Jakarta Persistence (formerly JPA).

As for why these samples use EJB and not CDI -- probably because CDI was really just beginning back when the samples were introduced (in EE 5/6 timeframe). Adding more CDI and Persistence samples would be great, I think.

In terms of being able to build/modify/test these samples, the notion was,  just let the IDE handle most of the build and deploy steps -- and they generally support source level debugging. We used to work closely with the NetBeans -- now, many IDEs have similar functionality -- they glean, either with their own custom setup, or they use some established inter-communications to perform the required steps. One thing that the EE specification never settled on was how each Platform would perform these administrative steps. That is why it's frequently left out of the documentation text.

The neutrality goal of Jakarta EE frequently makes documentation like this more difficult since we could be obligated to provide multiple recipes -- to avoid offending any vendor. Walking a user through a detailed, step by step recipe for manual build, deploy, run -- may well be something best left to each application server platform since it's likely to have a common general outline but differ enough at the detail level that each recipe would need to be customized before it would be useful to a reader. Perhaps these specific patterns could be refactored into separate, included doc files.

I am sure that fee based copies of IntelliJ can handle much of this workflow though I can't be sure that these apps. are all in the right layout  (some are so old current IDEs don't do so well with the older structure). I don't know what the latest status of NetBeans or Eclipse IDE is, with respect to this code.

We'd want to coordinate what happens with these samples, as well as work in the Tutorial to see how we want to address alignment. Coming up with a way for a reader to access the generic build/run/test workflow for each EE Platform would be a nice addition ... to all these sample/tutorial documents.

If you want to look at the latest Tutorial docs, that might be helpful.

Lastly -- if there isn't already a strategy for managing across multiple versions, you might want to consider that. We want to update Jakarta EE major versions more rapidly and it would be nice if we can, relatively easily generate releases (tags, or whatever is most appropriate) and also keep web-site copies updated and archived for each version as we evolve the platform.

I agree, it seems like setting up a discussion / meeting might make some of this happen more quickly. I will confess that much of what I have above took a bit of time for me to look up.

Let me see if we get any nibbles on any of the discussion lists.

-- Ed

On 6/27/2021 5:51 PM, Andy Gibson wrote:
Thanks both for your thoughts. Ed, your points were interesting because I didn't know how the different examples fit together, or which were still relevant, which I guess is something that we should look at. Maybe a single page linking the different example options with a description. You may already have this, if so it's pretty well hidden :-), but it would be great if many of the jakarta projects could reference that page in their ReadMe. This would get some exposure to the examples and give developers the confidence that the links are still relevant and updated. 

I did take the liberty of looking at the firstcup tutorial and despite being asciidoc, the end result doesn't have that typical asciidoc look or layout. I played around trying to get it looking how most asciidoc projects work, and how the jakarta tutorial project looks by basing it off the jakarta tutorial pom instead. You can see a working implementation of that here ( - my web site) and the original here ( ).  (disclaimer, I have not completely read the altered site so if there are big errors, I haven't  found them yet) I think the new version looks much cleaner and it uses practically the same pom as the jakarta tutorial - opportunity for some code reuse there and creating a standard template for jakarta docs, maybe even some custom theming across the board later on. It would be nice to make a standard archetype of jakarta docs.

Quick questions - 
What is the minimum version of Java that the examples should require? I know a lot of people are still on 1.8, but do we aim to use at least 11 or later? 
Are we still looking to remove ejbs and rely mostly on CDI? Most of the JPA examples utilised an Ejb to do any work for example.
I did find it difficult to get examples running, partly because there are no instructions, and partly because just starting a server and dropping the war in there didn't work.
Is there an empirical reference to the Jakarta EE API Javadocs anywhere? If I wanted to provide a link to the @Column or @Inject annotations, is there somewhere I can point to that is semi-permanent?

I would be open to having a call to discuss, push it back a bit so I can get a better look around some more of the pieces before we talk.



On Fri, Jun 25, 2021 at 1:38 AM Ed Bratt <ed.bratt@xxxxxxxxxx> wrote:

I think there is always room for improvement in the EE examples and sample code.

The collection of material is pretty extensive -- and it's evolved over different time periods. Generally, one might start with the "First Cup" tutorial -- this just shows a user how to download and start using Jakarta EE -- From there, a user might want to venture into the Jakarta EE Tutorial -- probably picking and choosing the sections or technologies they have any interest in -- interspersed in these, that user would want to be learning the details of their favorite IDE, and their favorite EE Application Server (e.g. GlassFish Samples and GlassFish product documentation) -- From there, the EE examples are intended to provide specific, targeted use cases and as you've seen, they aren't showing much about a cohesive, complete application. From there, (or perhaps at the same time) something like CargoTracker can be used to show a more complete and modern application -- and there are other example applications can be used to illustrate how to pull a multitude of EE technologies together into a non-trivial application.

The Java EE Samples (what became Jakarta EE Examples) project was forked and became JavaEE Samples several years ago and that fork has been evolved beyond what is included here in the Jakarta EE collection. If these samples are worth someone's time and effort to expand upon, we might want to consider if there would be any benefit in trying to merge these efforts back together. We could open a discussion with the relevant parties, if you have any interest in pursuing this.

There's no need to stick with GlassFish, or with a particular IDE -- and, it would be great if there was more diversity in these documents but, this is what was inherited and the community hasn't evolved the network of this material much.

As Reza said, we welcome your input.

I'd be happy to help you as well.

-- Ed

On 6/24/2021 4:33 PM, Reza Rahman wrote:

Welcome back to the ecosystem Andy!

I think the Jakarta EE Examples need a major overhaul to be far more use-case driven much like the Spring Boot starters.

The current format has a certain use, but honestly it is more helpful to people who are not really newcomers but want to see a certain feature in action. That said, even that could use serious help including better readmes and better index pages.

I am happy to brainstorm and contribute to this if you and others are interested. Maybe we can schedule a call to talk about it?

Lastly, any contribution to Cargo Tracker is most welcome. Here are the current issues: I lead that project.

Reza Rahman
Jakarta EE Ambassador, Author, Blogger, Speaker
Please note views expressed here are my own as an individual community member and do not reflect the views of my employer.

On 6/24/2021 7:15 PM, Andy Gibson wrote:

I'm a long time Java developer and would like to volunteer some time to J2EE, or Jakarta EE as it is now. I thought I might ease back into it with some work on examples and/or docs. I've previously worked with JPA, CDI, and JSF mostly and blogged quite a bit about it a few years ago (  I've long been an advocate for J2EE and making it accessible through those blog posts and I'd like to continue that by way of contributing to the Jakarta projects themselves.

I've had a peek through the examples at and also at the cargo app. I have had a look at the issues for the examples project, but most content is getting on for over 2 years old.

My first impressions would be that most of the examples are minimalist, consisting of a couple of classes showing a particular feature, which is OK, it shows people just the bits they need to add to a class to get a feature working. There isn't much accompanying documentation to describe what that feature does or how it can be used. I noticed there is an issue #8 to Describe the JPA examples which might be a good place to start. Most of those issues don't have much info in them so if anyone has thoughts on what they should do, let me know.

I'm also wondered whether there is interest in another larger application which showcases the more modern features of JEE and Java. It could include documenting the features showing why they are used as well as how. I'm looking for a bit of a project to take on, and that might fit the bill, but for now, I can start by working with some of the existing examples or writing any missing one.

If you have any thoughts or ideas on where to start, please chime in!


Andy Gibson

jakartaee-examples-dev mailing list
To unsubscribe from this list, visit

jakartaee-examples-dev mailing list
To unsubscribe from this list, visit;!!ACWV5N9M2RV99hQ!fRzfk32o6m92LP3lD8vqgpxJO5ChvDqR5lsGrb58BIA-QMsRukYYjs4lL6OX-Ls$ 
jakartaee-examples-dev mailing list
To unsubscribe from this list, visit

jakartaee-examples-dev mailing list
To unsubscribe from this list, visit;!!ACWV5N9M2RV99hQ!dvLSP8AxFFHMrvv8_jxnlL81hehxLgm6aOpVnQqR55FB4EWpY-vQxq4B51REnn4$ 

Back to the top