[MNG-7553] New clean API with immutable model

[gnodet]

Related PRs:

• [MPLUGIN-441] Support for the new maven4 api maven-plugin-tools#117
• [MPLUGINTESTING-78] Switch to maven 4 and the new api maven-plugin-testing#24
• [MINSTALL-187] Switch to the Maven 4 API maven-install-plugin#35
• [MDEPLOY-301] Switch to the Maven 4 API maven-deploy-plugin#27
• [MCLEAN-123] Switch to Maven 4 API and the new api maven-clean-plugin#20
• [MCOMPILER-593] Switch to the Maven 4 API maven-compiler-plugin#147
• [MSHARED-1200] Switch to the Maven 4 API maven-filtering#46
• [MRESOURCES-308] Switch to the Maven 4 API maven-resources-plugin#35

[Tibor17]

If we want to use immutable objects, we should use Java Records. We still do not have Valhalla ready.
The developers often do not understand Java Memory Model and there is no guarantee that they would not make a mistake when they update any immutable object. The developers usually would not understand why ConcurrentLinkedQueue is preferable over ArrayList and List.copyOf() is ideal https://docs.oracle.com/javase/10/docs/api/java/util/List.html#copyOf(java.util.Collection), and so we should use List.copyOf() which means that we should switch the project to Java 10 - bad luck! Nobody would accept Java 10, I guess.

The immutable object should be fetched with data via a builder in constructor.
MavenProject and MavenProjectBuilder composition

public record MavenProject(MavenProjectBuilder builder) {
 
    MavenProject {
        dependencies = List.copyOf(builder.getDependencies());
        ...
        ...
        ...
    }
}

[gnodet]

If we want to use immutable objects, we should use Java Records. We still do not have Valhalla ready. The developers often do not understand Java Memory Model and there is no guarantee that they would not make a mistake when they update any immutable object. The developers usually would not understand why ConcurrentLinkedQueue is preferable over ArrayList and List.copyOf() is ideal https://docs.oracle.com/javase/10/docs/api/java/util/List.html#copyOf(java.util.Collection), and so we should use List.copyOf() which means that we should switch the project to Java 10 - bad luck! Nobody would accept Java 10, I guess.

The immutable object should be fetched with data via a builder in constructor. MavenProject and MavenProjectBuilder composition

public record MavenProject(MavenProjectBuilder builder) {
 
    MavenProject {
        dependencies = List.copyOf(builder.getDependencies());
        ...
        ...
        ...
    }
}

Have you had a look at the generated code or are those just general comments about java records / immutable objects ?

[Tibor17]

Yes I saw the MDO.

[gnodet]

Yes I saw the MDO.

So the objects from the model are immutable, they absolutely can not be modified.

So unless we raise the requirements to JDK 17, I don't see how we could actually use records / List.of(). That said, I'm not sure there's actually much difference at the end. Of course, using records would be less verbose, but given we don't have to maintain that code manually (because it's generated), I'm not sure it really matters. For the List.of(x) point, the model already uses immutable lists, though those use Collections.unmodifiableList(xxx) to be JDK 8 compatible.

[Tibor17]

Don;t use Collections.unmodifiableList(xxx). It is vert old style - before year 2004 where the constructors where not thread safe, a typical findings with String and final fields - therefore Java changed impl for JMM of field semantics, used memory bariers at the end of constructor to make fields coherent with main mem, see JSR 133 https://download.oracle.com/otn-pub/jcp/memory_model-1.0-pfd-spec-oth-JSpec/memory_model-1_0-pfd-spec.pdf?AuthParam=1648805410_6b63e95379a8c30dbb165b2da54c9d0d

[gnodet]

Don;t use Collections.unmodifiableList(xxx). It is vert old style - before year 2004 where the constructors where not thread safe, a typical findings with String and final fields - therefore Java changed impl for JMM of field semantics, used memory bariers at the end of constructor to make fields coherent with main mem, see JSR 133 https://download.oracle.com/otn-pub/jcp/memory_model-1.0-pfd-spec-oth-JSpec/memory_model-1_0-pfd-spec.pdf?AuthParam=1648805410_6b63e95379a8c30dbb165b2da54c9d0d

Sorry, I don't get the point of immutable collections vs memory semantics. I agree we should use List.of(xxx) if we were to raise to JDK 17, but I'm not sure there's a consensus there. What do you propose I use instead for immutable collections ? Also, in case you missed the point, I'm always using

list != null ? Collections.unmodifiableList( new ArrayList<>( list ) ) : Collections.emptyList()

in order to make sure the collections are actually safe and immutable.
I can re-implement a custom unmodifiable collection to avoid the double creation, but that's more an optimisation to me rather than an actual problem.

[gnodet]

All tests are passing. I'd like to go on and merge this PR (and release an alpha version if possible). This would allow further work on other components and plugins (see the various PRs in this PR description) which are blocked because the API is not available in any public release or snapshot version.

[slawekjaranowski]

👍 for merge and for release alpha

[cstamas]

👍 as well, will take a deeper look tonight... but that should not block anything

[vlsi]

Consider using Nonnull by default, so the only place when you need to document nullability becomes @Nullable.

For instance, jspecify did not include @NonNull for a long time, and now they say @NonNull is rarely needed: https://github.com/jspecify/jspecify/blob/fa7b1d8654e5ec0696b5a8a8c49e275a2121aafd/src/main/java/org/jspecify/nullness/NonNull.java