Page History

It is difficult to control how public or protected data members fields are accessed. Attackers can manipulate such members in unexpected waysfields to violate class invariants or they may be corrupted by multiple threads accessing them concurrently [Bloch 2008]. As a result, data members fields must be declared private {??? or package private ???}. Use wrapper accessor methods to expose class members that are to be accessed outside of the package in which their class is declared. Using wrapper methods enables appropriate monitoring and control of the modification of data members (for example, by defensive copying, validating input, and logging). The wrapper methods can preserve class invariants-private.

Noncompliant Code Example (Public Primitive Field)

In this noncompliant code example, the data member total keeps track of 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 data memberfield, total can be altered by external client code independently of the add() and remove() methods. It is poor practice to expose fields from a public class [Bloch 2008].

Compliant Solution (Private)

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 so that the required member can be accessed beyond the current package. The .  The add() and remove() methods modify its value without violating any while preserving class invariants.Note that care must be taken when providing references to private mutable objects from accessor methods (see OBJ05-J. Defensively copy private mutable class members before returning their references for details). 

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

  public int getTotal () {
    return total;
  }

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

It is good practice to use methods such as add(), remove(), and getTotal() to manipulate the private internal state. These methods Accessor methods can perform additional functions, such as input validation and security manager checks, before manipulating the state.  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).

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 (Provide Wrappers and Reduce Accessibility of Mutable Members)

Mutable data members that are static must be declared private:

...

Depending on the required functionality, wrapper methods may retrieve either a reference to the HashMap, a copy of the HashMap, or a value contained by the HashMap. This compliant solution adds a wrapper method to return the value of an element given its index in the HashMap.

Exceptions

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

...

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

Risk Assessment

Failing to declare data members private can defeat encapsulation.

Automated Detection

Detection of public and protected data members 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

...