Deprecate Immutables in favor of Lombok

We seem to have settled on Lombok as the preferred solution for convenient creation of immutable classes in Java Lagom applications.

There’s a bit of clean up we can do to clarify this:

• Update the “Immutable Objects” guide to remove references to Immutables or deemphasize it
• review the java section of docs for isolated references to immutables library (see line 12 in https://github.com/lagom/lagom/blob/master/docs/manual/java/guide/cluster/Serialization.md)
• Include instructions for Lombok in the IDE setup guide
• Get rid of “Set up Immutables in your IDE” or relegate it back to an appendix
• Ensure we use Lombok consistently for value objects in sample apps and update their README files to clarify that you’ll need to setup Lombok with your IDE in order to load the project
• Include Lombok in the template Java projects (Maven archetype and giter8)
• Replace uses of Immutables with Lombok in Lagom’s tests
• Deprecate the lagom-javadsl-immutables library and externalize it to a separate repository

[jroper]

It’s a bit of a shame really. I’m just glad I can use Scala and not have to deal with issues like this in Java. People complain about a lot of things in Scala, but I have never once heard Scala developers complain about Scala preferring and strongly encouraging the use of Option in place of null, that’s always something that is put in the advantages column. Option tends to be one of the first things people who switch from Java to Scala fall in love with, so the author of Lombok I think is standing all by himself with that opinion there, possibly from a position of ignorance, though I don’t know if he’s ever used Scala in anger or not.

We don’t force anyone to use Optional in their data objects, though our APIs, as much as possible, never return null. We leave it up to the end user to decide what they want to use. If Optional is important to you, then perhaps it may make sense to use Immutables. The reason we moved away from Immutables is that getting it working nicely in an IDE ended up being far too painful, it was a huge roadblock to a smooth getting started experience in Lagom. So it seems to be a choose your poison situation, with the ideal experience being to switch to Scala.

[TimMoore]

I think it could totally be done in a series of smaller PRs. I updated the list above to be a checklist so that we can track as each part is completed.