Alternate staged builders that handle optional, etc.

[Randgalt]

A variant of staged builders is available that only stages required record components. Any optional components (when addConcreteSettersForOptional is enabled) are not staged and are added to the final stage. Additionally, if Collection options are enabled, those too are added to the final stage.

Closes #170

attn: @olsavmic

Reviewers - please test various use cases. I'm not very familiar with this feature and did what I thought was right.

[olsavmic]

This is perfect! I'm going to test it on our codebase and report possible issues in the next few days.

I don't expect any though, this is the design I envisioned, thank you!

[Randgalt]

Let me know and I'll merge.

[olsavmic]

There is a bug when immutableCollections are enabled together with STAGED_REQUIRED_ONLY option. The code does not compile, as the stage for the collection is detected as NOT REQUIRED yet the builder is not generated.

See #182 for a reproducer.

[olsavmic]

Fix for the bug is in 9632f41.

---

The configurations around collections and nullability are getting pretty complicated :/
I'll test the different combinations, but I'll mainly try to come up with a description of the sane mutual configurations for these options

useImmutableCollections / useUnmodifiableCollections (changes behavior with defaults)
allowNullableCollections
interpretNotNulls
nullablePattern

[olsavmic]

The changes in #182 make it work for us, but as I said above, the behaviour with nullability is now not uniform.

I'd consider merging this change and then discuss the following proposal:

"1st" layer:

• Define whether fields are @Null by default or @NotNull by default - that information is then combined together with annotations, allowing them to override the defaults.
  • @null by default, @null field -> Null
  • @null by default, @NotNull field -> NotNull
  • @NotNull by default, @null field -> Nullable
  • @NotNull by default, @NotNull -> NotNull

"2nd" layer:

• interpretNotNulls is configuring just the runtime checks behavior

  • When a field is resolved as NotNull, a runtime check is generated (regardless of whether it's a collection or not)

• allowNullableCollections

  • false -> Automatically set to empty collection
  • true -> may be NULL (but the runtime check still applies, meaning that NotNull field would throw if it's not set and interpretNotNulls is true)

• Anytime field is resolved as NotNull, it is required in the STAGED_REQUIRED_ONLY

[Randgalt]

@olsavmic I agree some of the options have gotten out of hand. Too many cooks and not enough quality. I'd like to deprecate a lot of it and re-work it.