Affects Version/s: 0.9.2
Fix Version/s: 0.10.0
As mentioned in passing in
MDA-221, the MDA bean API for collection property setters is both complex (in some cases, handling collections containing null elements although these seldom arise and are not compatible with a lot of the recent Java APIs) and inconsistent (e.g., sometimes allowing null parameters to represent an empty collection, sometimes not).
For 0.10, which is probably the last time we get to make major changes to the API, I'd like to have all bean collection properties adhere to the following contract:
- The setter's parameter will be annotated with @Nonnull. If the code organically handles a null parameter, that's fine, but it's no longer part of the contract. The implementation does not have to check for a null parameter and handle it specially, and that includes not having to guarantee an NPE.
- The setter's parameter will be annotated as @NonnullElements. The implementation does not have to check for null elements. The expectation is that passing a collection containing null elements will be likely to result in an NPE.
- The setter's parameter will be annotated as @Unmodifiable.
- The getter will be annotated as either @Nonnull or @NonnullAfterInit. The latter case is expected to be rare, as it would only be used in cases where a default empty collection cannot make sense. In that case, @NotEmpty should also appear on both setter and getter.
- The getter will be annotated as @NonnullElements and @Unmodifiable.
The implementation will usually involve:
- A private field of some collection type, initialised to an empty, unmodifiable collection such as Set.of().
- If appropriate, the setter will check for lifecycle constraints.
- The setter will then set field = Set.copyOf(newValue);
- The getter will return field directly.