Update documentation

docs/pages/pmd/rules/java.md

@@ -119,7 +119,7 @@ folder: pmd/rules
 *   [AvoidDeeplyNestedIfStmts](pmd_rules_java_design.html#avoiddeeplynestedifstmts): Avoid creating deeply nested if-then statements since they are harder to read and error-prone to ...
 *   [AvoidRethrowingException](pmd_rules_java_design.html#avoidrethrowingexception): Catch blocks that merely rethrow a caught exception only add to code size and runtime complexity.
 *   [AvoidThrowingNewInstanceOfSameException](pmd_rules_java_design.html#avoidthrowingnewinstanceofsameexception): Catch blocks that merely rethrow a caught exception wrapped inside a new instance of the same typ...
-*   [AvoidThrowingNullPointerException](pmd_rules_java_design.html#avoidthrowingnullpointerexception): Avoid throwing NullPointerExceptions. These are confusing because most people will assume that th...
+*   [AvoidThrowingNullPointerException](pmd_rules_java_design.html#avoidthrowingnullpointerexception): Avoid throwing NullPointerExceptions manually. These are confusing because most people will assum...
 *   [AvoidThrowingRawExceptionTypes](pmd_rules_java_design.html#avoidthrowingrawexceptiontypes): Avoid throwing certain exception types. Rather than throw a raw RuntimeException, Throwable,Excep...
 *   [ClassWithOnlyPrivateConstructorsShouldBeFinal](pmd_rules_java_design.html#classwithonlyprivateconstructorsshouldbefinal): A class with only private constructors should be final, unless the private constructoris invoked ...
 *   [CollapsibleIfStatements](pmd_rules_java_design.html#collapsibleifstatements): Sometimes two consecutive 'if' statements can be consolidated by separating their conditions with...

docs/pages/pmd/rules/java/design.md

@@ -193,9 +193,33 @@ public void bar() {
 
 **Priority:** High (1)
 
-Avoid throwing NullPointerExceptions. These are confusing because most people will assume that the
-virtual machine threw it. Consider using an IllegalArgumentException instead; this will be
-clearly seen as a programmer-initiated exception.
+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, making it clearly seen as a programmer-initiated exception. 
+However, there are better ways to handle this:
+
+>*Effective Java, 3rd Edition, Item 72: Favor the use of standard exceptions*
+>
+>Arguably, every erroneous method invocation boils down to an illegal argument or state, 
+but other exceptions are standardly used for certain kinds of illegal arguments and states. 
+If a caller passes null in some parameter for which null values are prohibited, convention dictates that 
+NullPointerException be thrown rather than IllegalArgumentException.
+
+To implement that, you are encouraged to use `java.util.Objects.requireNonNull()`
+(introduced in Java 1.7). This method is designed primarily for doing parameter
+validation in methods and constructors with multiple parameters.
+
+Your parameter validation could thus look like the following:
+```
+public class Foo {
+    private String exampleValue;
+      
+    void setExampleValue(String exampleValue) {
+      // check, throw and assignment in a single standard call
+      this.exampleValue = Objects.requireNonNull(exampleValue, "exampleValue must not be null!");
+    }
+  }
+```
 
 ```
 //AllocationExpression/ClassOrInterfaceType[@Image='NullPointerException']