[java] Deprecate AvoidThrowingNullPointerException

[oowekyala]

Is your feature request related to a problem? Please describe.
The documentation of AvoidThrowingNullPointerException just contradicts itself...

Avoid throwing NullPointerExceptions manually. These are confusing because most people will assume that the virtual machine threw it. To avoid a method being called with a null parameter, you may consider using an IllegalArgumentException instead

But then 2 lines later the Effective Java quote contradicts this:

If a caller passes null in some parameter for which null values are prohibited, convention dictates that NullPointerException be thrown rather than IllegalArgumentException.

We should indeed throw NullPointerException to check a parameter; this allows the exception to be the same whether your parameter validation was done explicitly with eg Objects.requireNonNull, or "implicitly" by eg calling a method on the parameter. I think this trumps the justification that "people will assume that the virtual machine threw it", which is a really weak argument... When you debug an NPE, the first thing you do is jump to the line where it was thrown. If the line is throw new NullPointerException(), it's pretty clear that the JVM didn't throw it...

Describe the solution you'd like Deprecate and remove AvoidThrowingNullPointerException

Describe alternatives you've considered

Additional context