EXP01-J. Never dereference null pointers

Null pointer dereferencing occurs when a variable bound to the null value is treated as if it were a valid object reference and used without checking its state. Dereferencing a null pointer causes a NullPointerException to be thrown, which interrupts execution of the program or thread. Code conforming to this coding standard will consequently terminate, because ERR08-J. Do not catch NullPointerException or any of its ancestors requires that NullPointerException is not caught. 

Noncompliant Code Example

This noncompliant example shows a bug in Tomcat version 4.1.24, initially discovered by Reasoning [Reasoning 2003]. The cardinality() method was designed to return the number of occurrences of object obj in collection col. One valid use of the cardinality() method is to determine how many objects in the collection are null. However, because membership in the collection is checked using the expression obj.equals(elt), a null pointer dereference is guaranteed whenever obj is null and elt is not null.

public static int cardinality(Object obj, final Collection<?> col) {
  int count = 0;
  if (col == null) {
    return count;
  }
  Iterator<?> it = col.iterator();
  while (it.hasNext()) {
    Object elt = it.next();
    if ((null == obj && null == elt) || obj.equals(elt)) {  // null pointer dereference
      count++;
    }
  }
  return count;
}

Compliant Solution

This compliant solution eliminates the null pointer dereference by adding an explicit check.

public static int cardinality(Object obj, final Collection col) {
  int count = 0;
  if (col == null) {
    return count;
  }
  Iterator it = col.iterator();
  while (it.hasNext()) {
    Object elt = it.next();
    if ((null == obj && null == elt) ||
        (null != obj && obj.equals(elt))) {
      count++;
    }
  }
  return count;
}

Noncompliant Code Example

This noncompliant code example defines an isProperName() method that returns true if the specified String argument is a valid name (two capitalized words separated by one or more spaces).

public boolean isProperName(String s) {
  String names[] = s.split(" ");
  if (names.length != 2) {
    return false;
  }
  return (isCapitalized(names[0]) && isCapitalized(names[1]));
}

Method isProperName() is noncompliant because it may be called with a null argument, resulting in a null pointer dereference.

Compliant Solution (Wrapped Method)

This compliant solution includes the same isProperName() method implementation as the previous noncompliant example, but it is now a private method with only one caller in its containing class.  

public class Foo {
  private boolean isProperName(String s) {
    String names[] = s.split(" ");
    if (names.length != 2) {
      return false;
    }
    return (isCapitalized(names[0]) && isCapitalized(names[1]));
  }

  public boolean testString(String s) {
    if (s == null) return false;
    else return isProperName(s);
  }
}

The calling method, testString(), guarantees that isProperName() is always called with a valid string reference.  As a result, the class conforms with this rule, even though a public isProperName() method would not. Guarantees of this sort can be used to eliminate null pointer dereferences.

Compliant Solution (Optional Type)

This compliant solution uses an Optional String instead of a String object that may be null. The Optional class ([API 2014] java.util.Optional) was introduced in Java 8 to make dealing with possibly null objects easier, see [Urma 2014].

public boolean isProperName(Optional<String> os) {
  if (os.isPresent()) {
    String names[] = os.get().split(" ");
    if (names.length != 2) {
      return false;
    }
    return (isCapitalized(names[0]) && isCapitalized(names[1]));
  else {
    return false;
  }
}

The Optional class contains methods that can be used in the functional style of Java 8 to make programs shorter and more intuitive, as illustrated in the technical note by Urma cited above.

Exceptions

EXP01-EX0: A method may dereference an object-typed parameter without guarantee that it is a valid object reference provided that the method documents that it (potentially) throws a NullPointerException, either via the throws clause of the method or in the method comments. However, this exception should be relied upon sparingly.

Risk Assessment

Dereferencing a null pointer can lead to a denial of service. In multithreaded programs, null pointer dereferences can violate cache coherency policies and can cause resource leaks.

Automated Detection

Null pointer dereferences can happen in path-dependent ways. Limitations of automatic detection tools can require manual inspection of code [Hovemeyer 2007] to detect instances of null pointer dereferences. Annotations for method parameters that must be non-null can reduce the need for manual inspection by assisting automated null pointer dereference detection; use of these annotations is strongly encouraged.

Related Vulnerabilities

Java Web Start applications and applets particular to JDK version 1.6, prior to update 4, were affected by a bug that had some noteworthy security consequences. In some isolated cases, the application or applet's attempt to establish an HTTPS connection with a server generated a NullPointerException [SDN 2008]. The resulting failure to establish a secure HTTPS connection with the server caused a denial of service. Clients were temporarily forced to use an insecure HTTP channel for data exchange.

Related Guidelines

Android Implementation Details

Android applications are more sensitive to NullPointerException due to the constraint of the limited mobile device memory. Static members or members of an Activity may become null when memory runs out.

Bibliography