OBJ01-J. Limit accessibility of fields

It is difficult to control how public or protected fields are accessed. Attackers can manipulate such fields to violate class invariants or they may be corrupted by multiple threads accessing them concurrently [Bloch 2008]. As a result, fields must be declared private or package-private.

Noncompliant Code Example (Public Primitive Field)

In this noncompliant code example, the total field tracks the total number of elements as they are added and removed from a container using the methods add() and remove() respectively.

public class Widget {
  public int total; // Number of elements

  void add() {
    if (total < Integer.MAX_VALUE) {      
      total++;
      // ...
    } else {
      throw new ArithmeticException("Overflow");
    }
  }

  void remove() {  
    if (total > 0) {      
      total--;
      // ...
    } else {
      throw new ArithmeticException("Overflow");
    }
  }
}

As a public field, total can be altered by client code independently of the add() and remove() methods.

Compliant Solution (Private Primitive Field)

Accessor methods provide controlled access to fields outside of the package in which their class is declared.  This compliant solution declares total as private and provides a public accessor.  The add() and remove() methods modify its value while preserving class invariants. 

public class Widget {
  private int total; // Declared private

  public int getTotal () {
    return total;
  }

  // Definitions for add() and remove() remain the same
}

Accessor methods can perform additional functions, such as input validation and security manager checks, before manipulating the state. 

Noncompliant Code Example (Public Mutable Field)

This noncompliant code example shows a static mutable hash map with public accessibility:

public static final HashMap<Integer, String> hm = new HashMap<Integer, String>();

Compliant Solution (Private Mutable Fields)

Mutable internal fields must be declared private:

private static final HashMap<Integer, String> hm = new HashMap<Integer, String>();

public static String getElement(int key) { 
  return hm.get(key);
}

Depending on the required functionality, accessor methods may return a copy of the HashMap or a value contained by the HashMap. This compliant solution adds an accessor method that returns the value of an element given its index in the HashMap.  Make sure that you do not return references to private mutable objects from accessor methods (see OBJ05-J. Defensively copy private mutable class members before returning their references for details).

Exceptions

OBJ01-EX0: According to Sun's Code Conventions document [Conventions 2009]:

One example of appropriate public instance variables is the case where the class is essentially a data structure, with no behavior. In other words, if you would have used a struct instead of a class (if Java supported struct), then it's appropriate to make the class's instance variables public.

OBJ01-EX1: "If a class is package-private or is a private nested class, there is nothing inherently wrong with exposing its data fields—assuming they do an adequate job of describing the abstraction provided by the class. This approach generates less visual clutter than the accessor-method approach, both in the class definition and in the client code that uses it" [Bloch 2008]. This exception applies to both mutable and immutable fields.

OBJ01-EX2: Static final fields that contain mathematical constants may be declared public.

Risk Assessment

Failing to limit field accessibility can defeat encapsulation, allow attackers to manipulate fields to violate class invariants, or allow these fields to be corrupted as the result of concurrent accesses from multiple threads.

Automated Detection

Detection of public and protected fields is trivial; heuristic detection of the presence or absence of accessor methods is straightforward. However, simply reporting all detected cases without suppressing those cases covered by the exceptions to this rule would produce excessive false positives. Sound detection and application of the exceptions to this rule is infeasible; however, heuristic techniques may be useful.

Related Guidelines

Bibliography

OBJ00-J. Limit extensibility of classes and methods with invariants