2.0 - API design change to throw exceptions instead of returning nullables #9

Jonathing · 2025-10-20T14:45:33Z

This PR modifies the API design of Java Provisioner to throw exceptions instead of returning null of something goes wrong trying to locate or provision Java installations.

Depends on:

Please don't squash and merge through GitHub.com. I'll merge this myself with the proper tag(s) once approval has been granted.

LexManos

Basically, the issue is he is wanting to expose more information in the event of failures. Which is fair. But throwing Exception everywhere is not the way to do it.

Better option is to grab the log from LogUtils and print that out when versions can't be provisioned/found.

Aside from that there are some other minor changes like the ordering of distros and nullability. Which we've discussed on discord and should be on the same page about.

LexManos · 2025-10-20T17:19:37Z

src/main/java/net/minecraftforge/java_provisioner/Disco.java

+        try {
+            return Objects.requireNonNull(readJson(tmp, TypeToken.get(DownloadInfo.class)).info);
+        } catch (Exception e) {
+            errors.add(e);


Reminder about Objects.requireNonNull

LexManos · 2025-10-20T17:20:47Z

src/main/java/net/minecraftforge/java_provisioner/Disco.java

-            error("Failed to download package info for "+ pkg.id);
-            return null;
+            error("Failed to download any packages from " + url);
+            throw Throwing.withSuppressed(new Exception("Failed to parse package list from " + url), errors);


The exception and error message are not aligned here.

LexManos · 2025-10-20T17:23:14Z

src/main/java/net/minecraftforge/java_provisioner/Disco.java

-                return null;
+            try {
+                DownloadUtils.tryDownloadFile(true, archive, download);
+            } catch (Exception e) {


This is broken because the return will be false, not an exception thrown.

Still relevent

LexManos · 2025-10-20T18:17:47Z

src/main/java/net/minecraftforge/java_provisioner/Disco.java

+    //      Prefer TCK certified JDKs (and also test Microsoft)
    public enum Distro implements Comparable<Distro> {
-        // These are well know/recommended distros
+        // These are well-known/recommended distros


So, discussing this on discord, just reiterating it here. I don't particularly care.
But MS > OpenJDK > Temurin > * > JDK > OpenJ9 seems to be the consensus on the order.

src/main/java/net/minecraftforge/java_provisioner/GradleLocator.java

LexManos · 2025-10-20T18:23:30Z

src/main/java/net/minecraftforge/java_provisioner/GradleLocator.java

-        for (File child : root.listFiles()) {
+        File[] listFiles;
+        try {
+            listFiles = Objects.requireNonNull(root.listFiles());


Another requiresNotNull and immediately caught exception.

LexManos · 2025-10-20T18:25:04Z

src/main/java/net/minecraftforge/java_provisioner/api/IJavaLocator.java

     * @return null is no install found, or a File pointing at the JAVA_HOME directory
     */
-    File find(int version);
+    File find(int version) throws JavaLocatingFailedException;


throwing an exception here to give more information then a null would is fine.

LexManos · 2025-10-20T18:26:05Z

src/main/java/net/minecraftforge/java_provisioner/api/IJavaLocator.java

     * @return A list containing all java installs, possibly empty but not null.
     */
-    List<IJavaInstall> findAll();
+    FindResult findAll() throws JavaLocatingFailedException;


Throwing an exception here is not find as it is meant to return all available entries. Not caring for things that are broken/whatever. Its just "What are my functional options"

LexManos · 2025-10-20T18:26:58Z

src/main/java/net/minecraftforge/java_provisioner/api/IJavaLocator.java

-    List<IJavaInstall> findAll();
+    FindResult findAll() throws JavaLocatingFailedException;
+
+    interface FindResult {


If you must keep this, rename to Results.
Tho I suspect this could be resolved with:

if (ret.isEmpty()) print(Log.getErrorMessages())

Ya, the interface was only because I wasn't printing the errors. I'll remove it when I redo this.

LexManos · 2025-10-20T18:28:24Z

src/main/java/net/minecraftforge/java_provisioner/api/IJavaLocator.java

+    }
+
+    default IJavaInstall provision(int version, Disco.Distro distro) throws JavaProvisioningFailedException {
+        throw new JavaProvisioningFailedException("Provisioning is not implemented by this locator");


If we throw an exception here, we need to add a 'canProvision' so we don't use exception as codeflow. Tho the only thing that can provision right now is Disco.

Would it be better to just make a subinterface? IJavaProvisioner extends IJavaLocator.

That'd work for me.

Jonathing · 2025-10-27T21:42:39Z

All extra exceptions have been removed, and I've done some extra tweaking to the API. Still a breaking change, so it still needs the 2.0, but I think it's in a better spot now with the lack of a logging API. Consumers are now expected to handle logOutput(), and the main classes use System.out and System.err.

src/main/java/net/minecraftforge/java_provisioner/api/JavaInstall.java

src/main/java/net/minecraftforge/java_provisioner/api/JavaLocator.java

src/main/java/net/minecraftforge/java_provisioner/Disco.java

PaintNinja

Looks ok from a quick scan on my phone, left some minor non-blocking questions and leaving the more detailed review to Lex

src/main/java/net/minecraftforge/java_provisioner/api/Distro.java

src/main/java/net/minecraftforge/java_provisioner/JavaHomeLocator.java

src/main/java/net/minecraftforge/java_provisioner/api/Distro.java

src/main/java/net/minecraftforge/java_provisioner/ProcessUtils.java

src/main/java/net/minecraftforge/java_provisioner/JavaVersion.java

src/main/java/net/minecraftforge/java_provisioner/Disco.java

src/main/java/net/minecraftforge/java_provisioner/DiscoLocator.java

src/main/java/net/minecraftforge/java_provisioner/DiscoMain.java

src/main/java/net/minecraftforge/java_provisioner/GradleLocator.java

Jonathing · 2025-10-28T14:09:02Z

Ready for another pass from @LexManos.

LexManos · 2025-10-28T16:58:15Z

Looks fine to me

Jonathing · 2025-10-29T16:50:27Z

I am merging this immediately.

…ables (MinecraftForge#9)

Jonathing marked this pull request as draft October 20, 2025 14:45

This was referenced Oct 20, 2025

0.4 - Java 25, Complex OS Rules, Log Cache Misses, and Java Provisioner 2.0 MinecraftForge/MinecraftMavenizer#6

Merged

[7.0] Lots of fixes MinecraftForge/ForgeGradle#998

Draft

LexManos requested changes Oct 20, 2025

View reviewed changes

Jonathing force-pushed the feat/jonathing/2.0/api-changes branch from 7ec0aa7 to 33339f5 Compare October 27, 2025 21:41

Jonathing marked this pull request as ready for review October 27, 2025 21:42

Jonathing requested a review from LexManos October 27, 2025 21:42