JAVA.FUNCS.IRV.PURE : Ignored Return Value for Pure Function (Java)

Summary

A call to a pure method is performed and the returned value is missing or discarded.

The return value is the result of the computation of a method. In some cases, it is expected that this return value gets used rather than dropped, since it contains important information about the outcome of the method or since otherwise the call to the method or constructor would be useless and hence meaningless. The latter situation occurs for calls to pure methods or constructors, that is, code that does not modify the heap memory of the caller. In many cases, this latter situation is the sign of more serious problems in the algorithmic logic of the code.

Tolerating Calls to Methods without Side-Effects

From time to time, it might be useful to instruct the analyzer to tolerate calls to specific methods, although they have no side-effects. For instance, this might be the case of calls to methods that check a condition and throw an exception if the condition does not hold. They are often used as assertions and such calls are not normally wrapped inside a try/catch scope. When this is the case, the programmer can annotate the method with the @TolerateUselessCall annotation, as in the subsequent example:

public static @TolerateUselessCall <T> T notNull(final T object, final String message, final Object... values) {
    if (object == null)
      throw new NullPointerException(String.format(message, values));

    return object;
  }

Without that annotation, a warning would be issued at each call to method notNull().

Properties

WARNING_FILTER += discard class="Ignored Return Value for Pure Function (Java)"

Example

Consider the following program:

import java.io.File;

public class Test {
  private String name;
  private static int counter;

  public Test(String name) {
      this.name = name;
  }

  public Test(String name, int offset) {
      this(name);
      counter += offset;
  }

  public static void main(String[] args) {
      File file = new File("dir");
      file.mkdir();    // Ignored Return Value (Java) warning issued here
      Test t = new Test("John");
      t.getName();     // Ignored Return Value for Pure Function (Java) warning issued here
      new Test("Joan"); // Ignored Return Value for Pure Function (Java) warning issued here
      new Test("Albert", 13);               // ok: has a side effect
  }

  public String getName() {
      return name;
  }
}

In this example, the programmer should for instance modify the program as follows.

import java.io.File;

public class Test {
  private String name;
  private static int counter;

  public Test(String name) {
      this.name = name;
  }

  public Test(String name, int offset) {
      this(name);
      counter += offset;
  }

  public static void main(String[] args) {
      File file = new File("dir");

      if (!file.mkdir()) {
            System.out.println("directory could not be created");
            System.exit(0);
      }
      new Test("Albert", 13);
  }

  public String getName() {
      return name;
  }
}

Calls to Pure Methods that Throw Exceptions

The analyzer does not issue any warning if a call to a pure method, whose return value is not used, is wrapped into a try statement with a non-empty catch clause. In that case, the analyzer understands that the call was not meant to modify the heap but rather to check for some condition, expressed through an exception. For example, in the following program, only one Ignored Return Value for Pure Function (Java) warning is issued, in test1(). The other call to this.getClass().asSubclass(Serializable.class), in test2(), does not trigger a warning.

import java.io.Serializable;

public class InstanceChecks {

  public static void main(String[] args) {
    InstanceChecks ic = new InstanceChecks();
    ic.test1();
    ic.test2();
  }

  private boolean test1() {
    this.getClass().asSubclass(Serializable.class); // "Ignored Return Value for Pure Function (Java)" warning issued here.
    return true;
  }

  private boolean test2() {
    try {
      // useful, since we check if an exception is raised
      this.getClass().asSubclass(Serializable.class);
      return true;
    }
    catch (ClassCastException e) {
      return false;
    }
  }
}

Resolution

Use the return value of the method or remove the method or constructor call completely, since it has no effect on the heap of the caller, or check if the logic of the code is broken because the return value of a call to a pure method or constructor is not used.

Relevant Configuration File Parameters

The following configuration file parameters affect checks for this warning class.

• REPORT_SIMILAR_WARNINGS
• WARNING_FILTER