It is a darn shame that JakartaEE and Microprofile are still not together (just my humble opinion). The fact is that both are incomplete without the other. In my archetypes I have put them together because I think they should be. Having said that I completely understand that it may not be politically advisable at this time to combine them. The trouble is that Runtimes like Payara just give them to you even if you do not define them. As long as they are separate but open source projects they should be usable right? Spring uses every kind of dependency they need. Why shouldn’t we? But this discussion should not keep us from coming together and make something nice :-)
@Reza I agree with almost all your points on my code. It is clear that you took a good look at them :-)
I tent to document my work with actually usable things. That is the reason behind the bash scripts. If something is a command why not make it executable? It brings its own form of documentation.
I have indeed never integrated my code with github actions. I have never had the time te really dive into the actions and it is till on my todo list and some of my archetypes are from before github actions were launched :-). I will bump it up on my priority list.
I most certainly agree that most of the code should work on its own without docker. I am a docker fan and I made the archetypes in essence for myself… so docker is a logical choice for me. I hate installing software if I do not have to :-)
The license issue is IMHO solved easily right? I’ll just change them. I have that right or don’t I as the sole committer on my projects?
@Edwin I like your summary. And yes the state of my archetypes represent the need I had at the time. They are actually a very minor effort on my part, but as I have some users I feel obliged to update the archetype(s) now and again even if I am not actively working on or with them at this time. This is my main drive to start this discussion and hope to find a way to work together.
@Reza do you have an idea on what I can do to prepare for a more easy merge? I have no ego as far as my archetypes are concerned, we can do nothing, anything or everything to them as far as I am concerned. My ego emerges only on discussions pertaining clean code and best practices and the like 😄.
Is there a clear idea on what the UI needs to do?
- will we be working with archetypes the user needs to run themselves or generate a zip like Spring does?
- do we actually want the same thing as spring does?
I have caught up with this thread but haven't found time to look at the code myself - yet. Though I would like to respond to your comments.
I think your summary/analysis is very sound and feel that I would make the same conclusions when diving into the project. After all, I know where the project came from so I have a bit of background knowledge. What I would like to say is that you are right that we need to fix some issues regarding the Jakarta EE/MicroProfile alignment, Maven and Docker relation and or dependencies in the project. The fact that the project is in a certain state and does or doesn't contain some features, is because it came from Ivo's mind to experiment with the full stack. It's not impossible to decouple things if effort is put into this, and Ivo agrees with this of course.
Please correct me if I'm wrong but I hope this project forms a solid base for starter efforts to come.
One additional detail to add - if we all agree the UI experience is not centered on surfacing the use of Archetypes that the user then needs to manually invoke themselves but should be more like what the Spring/Quarkus/MicroProfil/etc starter experience looks like, we still need to sort through what the backend technology for the UI will be. I suggest going with whatever is most easily provided by the Eclipse Foundation. Invoking an Archetype behind the scenes can be done with anything that can make a command line invocation on the server-side (could even be node.js if we want to stick to JS on the server-side too).
As promised, I took some time to carefully take a look at Ivo’s work. I am sharing my thoughts on it. I hope other folks here also do a bit of analysis and chime in with their thoughts so we can move forward to deliver value for the community.
I think the clearest alignment is with regards to bringing in the UI. I think the current UI code exposes too much of the underlying Archetypes. I think from a UI perspective, the fact that Archetypes are used under the hood at all are an implementation detail. The user should mostly be concerned with higher level functional parameters such as the generation use case (e.g. minimal/REST CRUD/JSF CRUD/etc), Jakarta EE version, target runtime, generated artifact metadata and so on. This is after all the experience for the Spring initializer, etc. However, overall I think these are minor deltas and UI code looks fairly sound.
The code is definitely focused on minimal generation, just with a simple POM, Jakarta EE deployment descriptors and a very simple hello world REST endpoint. I don’t think it does any real harm to add this option to the starter here. Overall, the amount of additional code would be very small (perhaps in the order of a few hundred lines). I do think the nature of the generated code is different enough to warrant *one* separate Archetype with a robust post processing script that handles minor variants like target runtime and Jakarta EE version.
The examples mix and match MicroProfile and Jakarta EE. Given the ongoing Jakarta EE and MicroProfile alignment conversations, I think we need to tread carefully here and maybe even ask for advise from the Jakarta EE steering committee/platform specification. For one, it makes the situation odd for runtimes like GlassFish. My inclination is to stick to vanilla Jakarta EE in this starter for now and just stay out of a potentially contentious conversation.
The code makes no effort in trying to use Maven plugins to have a self-contained runtime experience right from Maven (e.g. mvn clean package tomee:run). Honestly I believe this is a mistake. With embedded runtimes like Spring Boot, Quarkus, etc developers expect to run/test applications right from Maven. I think even in a minimal starter project, having this is important in order to position Jakarta EE as something modern. This is what we have in the starter already for reference.
The code really is quite dependent on Docker, going as far as making an assumption that users must have a Docker Hub account. Honestly I think this too is a usability mistake. Many developers are still very new to containers so needlessly aligning too much with Docker is a potential usability hazard that I don’t think we really need to get into. It should be mostly possible to use the starter without Docker at all and still have easily running code.
The code has a number of scripts that abstract over relatively simple Docker commands. This can actually lead to the impression that using Jakarta EE with Docker is so difficult that you need scripts to deal with the complexity. I suggest we simply generate a Dockerfile and document the few relatively simple commands to build a Docker image that contains the Jakarta EE application and run the Docker image. This is what we have now for reference.
The code does not utilize GitHub Actions or any other kind of automated sanity checks/tests. I think we absolutely need that for a distributed project with many potential contributors.
There is no index page and the documentation is quite minimal. Since we have quite a bit more visibility as an official Jakarta EE umbrella project, we will obviously need to improve that.
If this all seems reasonable to most folks here, I am happy to begin working on a PR to basically merge the efforts (I may need a tiny bit of help with the UI as I am not that proficient with JS yet). I think this is small enough to just be a few evenings’ effort. I could get it done by the end of the weekend so we can keep focusing on forward progress delivering more releases.
Unfortunately with the popularity of the Spring initializer, I am afraid we have no choice but to have a UI. I do believe at least initially we need to focus on a simple UI. Certainly trying to present a “components” view of Jakarta EE is something we should prioritize lower at this time. I think it’s best to just evolve features including the UI over time. Part of the reason the project was stuck for so long is a lot of analysis paralysis around requirements and the UI. I think we should remain in a different gear now and focus a bit more on delivering working releases, even if incremental.
I do have to say that personally I believe a command line is all you need because the array of options indeed could be quite small. That’s why I would prefer we kept a mindset of being somewhat agnostic of a UI. Luckily as a side effect the IDE experience also remains nice as most IDEs have pretty good support for Maven Archetypes. It’s fairy easy to support all three pathways equally without too much work.
With regards to Gradle, I spoke with Bazlur and we feel we could easily do this without too much hassle using Maven to Gradle converters behind the scenes. The plan was to look at this once we have delivered a few more solid releases.
I should add that I am not necessarily totally against having a more minimal project generation option. What I am having trouble visualizing is what exact content is worth putting into a minimal option. Just a pom does not feel like it’s worth the effort because of the nature of Jakarta EE. Perhaps looking at what Ivo has might help. I will try to do that analysis by the end of this week. As such, adding a minimal option won’t “hurt” anything except for maybe a bit more code to maintain for us. Perhaps it can be done with a small amount of code. I’ll try to think about that once it’s a bit clearer what could be generated that makes reasonable sense.
I definitely feel strongly that a reasonably complete, working REST CRUD example is very important to have in the starter experience to increase adoption with new users for sure. There is already plenty of data points to support this need and plenty of precedent. Hopefully some of the folks that can already see that will chime in too.
Thanks, I'm also glad to see you joining this initiative. I know that it is your cup of tea from both a technical and teaching perspective, so your input is very much appreciated!
I'm still struggling with the GUI for generating Jakarta EE based projects, based on archetypes or not. It is indeed dead simple as you stated, because bootstrapping a Jakarta EE project is that simple. A Maven pom.xml file with the necessary provided Jakarta EE dependency, the required directory layout for Maven and optionally some basic files like persistence.xml and beans.xml would already be sufficient. Teaching people that this is all that's required to run on a compatible application server of their choice and which one: that's imho where the struggle is. New users often don't understand this concept ootb, and certainly not the value and benefits of this. They expect to click an interface, get a file back and be able to run it. Therefore: I get comments like:
- Jakarta EE is bad because it doesn't have a GUI like Spring or Quarkus. My option: no it doesn't because it doesn't necessarily need it other than the dead simple interface like you provided. Or the MicroProfile starter. You don't have to select components for Jakarta EE compatible projects.
- Jakarta EE is bad because it doesn't have (sufficient) Gradle support. My opinion: no it doesn't because it doesn't necessarily need it other than that the exact same build artifacts are generated by a different tool.
So getting to the question of the backlog items we want to process: to what extent do we want to adhere to the user's desires via command line, GUI and tooling support? I would suggest that we create a product vision for the starter that describes what we include, and want to teach people to use the right way, the Jakarta EE way. Anything else can be explained in a FAQ or tutorials or whatever why support for certain desires is not going to be implemented.
I like the initiative of this separate starter project and mailing list, separated from the usual Jakarta EE mailing list discussions. I don't have all the answers to the discussions yet but would like to share my two cents to participate:
- we have users that would like to see IDE and command line usage, and we have users that want a UI to generate a project. Why not both?
- using archetypes is to bootstrap a project indeed, with minimal content for a certain purpose. Generating a full fledged demo project from an archetype feels like stretching the concept, and begs the question: why?
- I would advise not to overdo and overvalue the use of archetypes. Having separate ones for certain purposes (is the cut-off point a major Jakarta EE version?) feels legit, is it really that much of a burden regarding maintenance?
I'll also have a look at the content and project and see what I can come up with.
I'll take a look and share my thoughts on what you have.
I suspect the primary issue is the amount of generated code and
the fact that you might be largely a solo effort and this effort
already needing to collaborate between a number of committers and
contributors. For solo efforts with very minimal archetypes the
complexity that arises from code duplication and needing to
maintain multiple archetypes and repositories is less of an issue.
I think if you explore the current code base a bit more, you'll
see why a simple change like adding a new runtime, fixing a bug or
making enhancements across needlessly duplicated code would be a
headache across a distributed team.
It also sounds like the command line and IDE usage as opposed to
UI usage may not be a primary concern for you. The reason we went
the Archetype route (which was not the original direction) is to
better enable command line and IDE usage. Having fewer Archetypes
to navigate makes the command line and IDE pathways easier to use
That said, another use case is definitely minimal archetypes that
just generate a POM. The question is whether that's a valuable
model for Jakarta EE. It certainly makes clearer sense for
something like Spring, Quarkus or even MicroProfile where the POM
itself is not so simple to compose.
With regards to the items on the issue list, they are quite dated
and probably should be thought of as long term wish list items at
this point rather than an actual committed roadmap. As we begin to
tackle those after we work through the roadmap items there are
higher levels of commitment on delivering
(https://github.com/eclipse-ee4j/starter#roadmap), we would
certainly evolve, perhaps logically in the direction of multiple
Archetypes. I think for now focusing too much on those does not
make sense yet (as opposed to say creating a UI, supporting more
popular runtimes or adding support for Jakarta EE 9.1).
The thing is I have maintained a couple of archetypes the last
couple of years and I have chosen to do that in separate
repositories because of the ease of use, maintaining and ease of
creating new ones. My post processing script is very simple and
always the same.
I hope that is enough of a demonstration of giving
clear names and easy code.
Why would having multiple repositories make
maintaining something more difficult? I do not see that at
all. If you need to change something for a specific archetype
you only have to do that for that archetype right? No other
archetypes needs to change. Also if you write a GUI like mine
you actually have to document less as the choices you have are
already clearly defined in the GUI. The GUI is dead simple
because all the archetypes follow the same routine but with a
different combination of tools. The telling names say it all.
So in my experience it is way easier to maintain a
very simple archetype than to maintain a difficult one. The
more the post processing script has to do the more difficult
it will become. Taking versions / incompatibilities /
different examples / etc. into account.
Right now I am creating an archetype for Glassfish
6.2.5 with JakartaEE 9.1 and Docker.
That is the only thing I want in that archetype. It
is almost trivial for me to make a new one based on another
example I already have or update that one to the new
version, but it is not as trivial for me to create a PR on
the official repo and that is why I haven’t yet.
I see a lot of requests for examples in the issue
The more examples you are going to put in the more exception
flows (lots of if statements) you need to write if you want
to jam that al into one repo. It is fantastically easy to
create all those examples in separate archetypes and
maintain them as they grow or need a new version.
On another note. Should a fully fletched demo be
put into an archetype? If I have to remove 80% of the code
every time I need to start a new project I will not use it.
How about you? Should examples not be tutorials with a repo
Archetypes are there to generate a specific
starting point for developers right? I know I am new to this
discussion but if the goal is newcomers isn’t an archetype
not a strange approach? I am not trying to be difficult but
I honestly don’t understand these choices. I think an
archetype should help developers to start coding, not to
give a demo.
BTW why do we not have official Glassfish docker
The GitHub Actions
Pipeline in the current project is already
designed to test out all the current options
per check-in or PR. Have you had a chance to
look at that? Whatever the project structure,
it would be important to have such automation
in place. I would say these needs are
basically the same no matter what the
As I alluded to
elsewhere, I personally have a hard time
understanding what the value proposition would
be for a very basic Archetype for Jakarta EE.
Because of the nature of Jakarta EE, the
essential Maven structure is always rather
simple. Would it really differ very much from
the Archetypes that Apache already has in the
catalog? Other than the Maven project
structure and POM, what other generated code
would be included if any? A Servlet or JSF
page? Is that really important these day? A
REST endpoint? Is that really different enough
from what’s there right now?
Anyway, a relatively
complete code example of what would be
generated would really help me understand (and
probably others too). How do you think one
could get that? Would it be possible to issue
a draft PR? Is it already available to see?
That would also help clarify the value for a
possible separate Archetype (that’s what I had
in mind for JSF as the generated code
including the unit tests and index page would
likely vary too much from the current REST
on behalf of Ivo Woltring <ivo@xxxxxxxxx>
Sent: Monday, May 2, 2022 3:07 AM
To: starter developer discussions
Subject: Re: [starter-dev] Starter archetypes /
GUI / Issue #67
If you make an archetype that can do a lot of
things and configure a lot then it becomes more
difficult by definition.
How do you test such an archetype
with all its options? Generate all combinations
with every change and see if it still works?
DRY is in my opinion not always the
best way to go, but I see your point.
What of a compromise?
A bare bones project with only the
maven project and Dockerfile of choice and one
with all the demo thingies and options in it.
One for new blood to learn and one
for those who just want a new project so they
can start jamming?
am happy to actually prototype
out what I had in mind so
folks here can take a look and
hopefully see for themselves
how much not a big deal this
am not saying that if the
generated project varies too
much in reaction to parameters
that there isn’t a sensible
case for creating a separate
Archetype. For example, I can
see a generated JSF CRUD
project being sufficiently
different from the current
REST CRUD generated code. But
fairly minor variations for
Jakarta EE versions and target
platform? I think that’s no
big deal at all. Even the
relatively simple Payara Micro
Archetype handles Jakarta EE
versions just fine as
have to be honest, I
really don’t see why
multiple Archetypes would
be any easier at all for
one Jakarta EE version to
another, the only things
that would change are
Jakarta EE dependency
versions, Java SE
versions, runtime versions
and package names. Those
could easily be expressed
as variables in the source
and filled out using
templates in the Groovy
post-script (Groovy even
has built-in template
engines for this). The
user simply needs to
specify the Jakarta EE
version as an Archetype
parameter. The Groovy post
script can then easily
replace a set of variables
depending on the user
input parameter. This of
course in addition to the
replacement technique we
already have in the Groovy
script. These simple
techniques avoid needless
complexity for the end
user and code duplication
while utilizing reasonable
going down the multiple
Maven Archetypes road, I
suggest taking a look at
how that would work. It’s
really quite simple,
flexible and robust. I can
dynamically generate just
the Java/Jakarta EE
package name for now to
demonstrate the technique
if you like. I’ll need
about a weekend’s time to
do that if this is a
priority right now.
need to be able to support
multiple versions of Jakarta
EE at the same time.
Support for EE
9 and EE 10 is crucial to
get out ASAP. For this we
have two options:
archetype that supports
the generation of multiple
Jakarta EE versions
archetype per Jakarta EE
I think that
2) will get us there
faster, and also reduce
the complexity of the
archetype. Thus apply WET
rather than DRY. It would
also be clear for the user
which version is being
generated by this being
reflected in the maven
coordinates. For example:
welcome idea, though
hopefully not an
"as-is" donation but a
needed? I think for
folks using it from
the command line and
IDE, just one
Archetype would be far
easier. As such, it is
very easy to
instead of exposing
the user to the
complexity of multiple
Archetypes I think
(you can hopefully see
that in the code
currently in the main
branch and various