User-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Thunderbird/78.11.0
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 (http://www.andygibson.net/blog/firstcup/
- my web site) and the original here (https://eclipse-ee4j.github.io/jakartaee-firstcup/toc.html
). (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.
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?
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:
Greetings,
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 (https://www.andygibson.net/blog/tag/java-ee/).
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 https://github.com/eclipse-ee4j/jakartaee-examples
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!