Add example of starting application via java -jar

[bdemers]

I'd love to see an option to start a project with an embedded runtime, and have it package a single jar.

Possibly by using SeBootstrap and an SeContainer, something like:

SeContainer container = SeContainerInitializer.newInstance()
  .addPackages(true, ExampleApplication.class)
  .initialize();

ExampleApplication app = new ExampleApplication();
SeBootstrap.start(app, SeBootstrap.Configuration.builder().port(8080).build())
  .thenAccept(instance -> instance.stopOnShutdown(stopResult -> container.close()));
URI uri = UriBuilder.fromUri("http://localhost/").port(8080).build();

System.out.printf("Application started: %s%nStop the application using CTRL+C%n", uri.toString());

[m-reza-rahman]

Is this a desire to see a standard API in Jakarta EE? If so, this is not the right place. The right place could be the Jakarta EE platform specification.

What we can do here is add example configuration to start the application via java -jar for runtimes that support that capability. Since our goal is just to help people get started and we already allow starting via Maven and Docker, I think this is a low priority for us. Typically producing a jar is done with the same Maven plugins we already include in the samples, so this would be an easy exercise for the user if they want to start via java -jar.

[bdemers]

The example above was a suggestion to use something like jakarta.ws.rs.SeBootstrap

Of the combinations on start.jakarta.ee I tried, all of the packaging types where war files.

IMHO, it's challenging for users to use these APIs, partly due to awareness of them, how to use them together (CDI, WS, etc), dependency hell, and then how packaging them (e.g. Maven)

[m-reza-rahman]

Do you realize long term the examples won’t be specific to just a REST endpoint? Also, the users need to be able to add other APIs on top of our starter code. That’s why the JAX-RS bootstrap won’t work as it ultimately targets a JAX-RS implementation, not a Jakarta EE runtime.

Given the above, can you kindly help me clarify what you are expecting? If you are expecting a general standard embedded API for Jakarta EE (and by extension for all Jakarta EE runtimes to support running applications via java -jar), we can’t provide that. The platform specification can. What we can provide is example configurations that will allow starting an application via java -jar, if a given runtime supports this feature (and most nowadays do, but not all and certainly not via the standard).

There is no point doing something without determining what the desired scope is. For example, even runtimes that do support running via java -jar often have war as their Maven package type. If what you are expecting is exactly what Spring Boot does (run via java -jar) in the exact way that it does it (embedded API with a Maven package type of jar with the runtime configured in Maven), that is the role of the platform specification, not us. If the expectation is to simply be able to run via java -jar, that is something we can do for most runtimes, using non-standard Maven plugins.

I also want to understand to what extent this is really needed given the ability to get the sample code running directly from Maven or Docker, without a separate effort to install a runtime yourself. Users that want to run via java -jar can always add their own Maven configuration later, often using Maven plugins we already include in the sample.

[bdemers]

I'm not trying to suggest a new API here, just using existing ones.

I agree this isn't a one size fits all request, and start.jakarta covers more than just JAX-RS apps.
But, the current wizard lets me select Core Profile which is basically a minimal JAX-RS app, and I'd like to create an applications that has a single (non-docker) bundle, similar to Spring Boot, Quarkus, etc

It's not an apples-to-apples conversation, but it's very similar to what start.spring.io has, package the app as a jar or war.

IMHO, don't think forcing a user to run the app via Maven or Docker provides a great developer experience (I say this as a big Maven fan), though providing examples for those is very important!.

I'd like to:

• Click on a main method and run it from my IDE
• Create a single jar that is easily deployable elsewhere (and not require Docker)

[m-reza-rahman]

I believe I have already sufficiently explained what we can and cannot do within the scope of our project.

We cannot provide an embedded API that can run via a main method because no such API exists in Jakarta EE. Even for the Core Profile, our target runtime cannot be limited to a JAX-RS bootstrap. We cannot produce a Maven package type of jar since Jakarta EE does not standardize that either.

What we can do is produce an example configuration of how to run the application via java -jar, for runtimes that support this in a non-standard fashion. That can be done for all profiles.

If this is not what you are looking for, there is no point leaving this issue open.

[bdemers]

Sorry, maybe I'm dense 🧠 🤷

If you cannot create a jar packaging, where would the java -jar example live?

[m-reza-rahman]

Each runtime handles this slightly differently today. Some like Helidon may indeed use a package type of jar while still allowing a web.xml. Others repackage the produced war inside a jar using their own plugin as a separate life cycle step (such as Open Liberty and WildFly). Yet others (like Payara Micro) simply provide their own runtime as a jar and allow passing in the war as a parameter. Either way, we can produce the correct configuration for Maven and tell the user in the README how to run using java -jar (just like we have generated README instructions on how to run directly from Maven or Docker). The first step will always be a Maven build to produce the application (likely a war, followed by other Maven invocations to repackage in one way or the other) before it can be run via java -jar.

Do you think this is sufficient for the UX you are looking for? Bear in mind, you can always follow up with the platform specification for any additional standards enhancements we just cannot handle here.

[m-reza-rahman]

A few more thoughts to ensure clarity. I really don’t think we can add a higher level UI option for this feature. The reason for this is that we want to avoid creating a false impression that Jakarta EE mandates packaging applications as jars or has some kind of standard Java SE bootstrap API. This today is very much a vendor specific feature, which we can add in the README as an optional add-on step with the Maven instructions. Honestly I think the proper way to approach this is starting in the platform specification so we could one day add it as a high level feature in the UI.