Page History

 chaining implementation consists of a series of methods that return the {{this}} reference. This allows a caller to invoke methods in a chain by performing the next method invocation on the return value of the previous method in the chain.

While the methods used in method chaining may be atomic, a chain of method calls is inherently non-atomic. Consequently methods that are involved in method chaining should not be invoked by multiple threads unless the caller provides sufficient locking as illustrated in [CON07-J. Do not assume that a group of calls to independently atomic methods is atomic]. 
 

h2. Noncompliant Code Example

Method chaining is a useful design pattern for building an object and setting its optional fields. A class that supports method chaining provides several setter methods that each return the {{this}} reference.  However, in a multithreaded environment, a thread may observe shared fields to contain inconsistent values. This noncompliant code example shows the JavaBeans pattern which is not safe for multithreaded use.

{code:bgColor=#FFcccc}
final class USCurrency {
  // Change requested, denomination (optional fields)
  private int quarters = 0;
  private int dimes = 0;
  private int nickels = 0;
  private int pennies = 0;

  public USCurrency() {}

  // Setter methods 
  public USCurrency setQuarters(int quantity) { 
    quarters = quantity; 
    return this;
  } 
  public USCurrency setDimes(int quantity) { 
    dimes = quantity; 
    return this;
  }
  public USCurrency setNickels(int quantity) { 
    nickels = quantity;
    return this;
  }
  public USCurrency setPennies(int quantity) { 
    pennies = quantity;
    return this;
  }
}

// Client code:
private final USCurrency currency = new USCurrency(); 
// ...

new Thread(new Runnable() {
  @Override public void run() {    
    currency.setQuarters(1).setDimes(1);
  }
}).start();

new Thread(new Runnable() {
  @Override public void run() {    
    currency.setQuarters(2).setDimes(2);
  }
}).start();
{code}

The JavaBeans pattern uses a no-argument constructor and a series of parallel setter methods to build an object. This pattern is not thread-safe and can lead to inconsistent object state. In this example, a client that constructs a {{USCurrency}} object and starts two threads as shown may find the object to contain two quarters and one dime or one quarter and two dimes, contrary to what it expects.


h2.

 {mc}


{code:bgColor=#ccccff}
final class USCurrency {
  private final int quarters;
  private final int dimes;
  private final int nickels;
  private final int pennies;

  public USCurrency(Builder builder) {
    this.quarters = builder.quarters;
    this.dimes = builder.dimes;
    this.nickels = builder.nickels;
    this.pennies = builder.pennies;
  }

  // Static class member 
  public static class Builder {
    private int quarters = 0;
    private int dimes = 0;
    private int nickels = 0;
    private int pennies = 0;

    public static Builder newInstance() {
      return new Builder();
    } 

    private Builder() {}
    
    // Setter methods 
    public Builder setQuarters(int quantity) { 
      this.quarters = quantity; 
      return this;
    } 
    public Builder setDimes(int quantity) { 
      this.dimes = quantity; 
      return this;
    }
    public Builder setNickels(int quantity) { 
      this.nickels = quantity;
      return this;
    }
    public Builder setPennies(int quantity) { 
      this.pennies = quantity;
      return this;
    }

    public USCurrency build() {
      return new USCurrency(this);
    }
  }
}

  // Client code: 
private volatile USCurrency currency;
// ...

new Thread(new Runnable() {
  @Override public void run() {    
    currency = USCurrency.Builder.newInstance().setQuarters(1).setDimes(1).build();
  }
}).start();

new Thread(new Runnable() {
  @Override public void run() {    
    currency = USCurrency.Builder.newInstance().setQuarters(2).setDimes(2).build();
  }
}).start();
{code}

The {{Builder.newInstance()}} factory method is called with the _required_ arguments (if any) to obtain a {{Builder}} object. The _optional_ parameters are set using the setter methods of the builder. The object construction concludes with the invocation of the {{build()}} method. This also makes the class {{Currency}} immutable, and consequently, thread-safe.