Java class and record generators and friends side-by-side

[protobufel2]

1. Java code generation via Java Records and
2. Wither implementation close to JEP 468
3. extra "generateRecords" option in Gradle JavaCodeGenTask
4. extra "--generate-records" option in pkl-codegen-java CLI
5. updated docs

see pkl-codegen-java/README.md

[bioball]

Thanks for this PR! This is a much needed feature.

I haven't looked at this in detail yet; worth discussing the implementation first.
Also, it's a little hard to review this because of the duplicated JavaRecordCodeGenerator class. Can we consolidate this?

[bioball]

I think we should just flip this around and have a flag called generatePojos which defaults to false.

By default, the code generator should be generating records whenever it can (all Pkl users are on Java 17).
This flag would just be for folks that are migrating and don't want to suffer a breaking change.

[protobufel2]

Regarding flipping generateRecords to the default true, it'd be very distractive, incompatible change by breaking all regenerated Java object models' usage, necessitating the corresponding boolean flip in Gradle extension and any such Java generation via using pkl-core or pkl-config-java by the affected users

[bioball]

I think that's okay; for users that want minimal breakage, they can add generatePojos = true to retain the current code generator output. For most users, this should be a matter of adding a line to their build.gradle.

[protobufel2]

Can we follow the industry practice of deprecation, keep things as compatible as possible for one, two releases before make it the breaking change? I guess, until Pkl goes 1.0.0 we could've followed Kotlin's model of making such breaking changes after a couple of minor releases, especially when it doesn't change the Pkl itself?

[bioball]

The downside of that is: it is harder for new users that are adopting Pkl (the code generator has less sensible defaults).

We usually try to minimize breaking changes, but this one feels quite tolerable to me. I'm also okay with already making the generatePojos option already deprecated, and eventually removed. Once we ship 1.x, we will be stricter about breaking changes.

[stackoverflow]

Thanks for the PR! Generating records is something we were already discussing since we switched to Java 17.
Just left some comments for the high level archtecture.

[protobufel2]

@bioball, @stackoverflow, @arouel please review and approve this hopefully final update to the PR, including:

1. introduced 2 new optional features, useWithers and useLombokBuilders, to the plain Java records generation - as per your request
2. refactored JavaRecordCodeGeneratorTest with JUnit 5 ParameterizedClass and tested all 3 cases: plain record generation, with Withers, and with Lombok Builders
3. Submitted the Java Records Code Generation SPICE SPICE-0017: Java Records Code Generation pkl-evolution#19 for your review and approval.

[protobufel2]

Also merged and reconciled with the unrelated 'generatedAnnotation' PR by @arouel released today into main, enabling it in both Java CodeGenerator and JavaRecordCodeGenerator for parity.

[protobufel2]

Reconciled with the unrelated 'generatedAnnotation' changing to addGeneratedAnnotation.