Page History

 Classes that support method chaining provide several setter methods that return the {{this}} reference. 

Method chaining should not be used in a multithreaded environment because chained invocations of a set of methods are non-atomic and, consequently, noncompliant with [CON07-J. Do not assume that a group of calls to independently atomic methods is atomic].
 

h2. Noncompliant Code Example

Method chaining is useful for building an object and setting its optional fields. However, in a multithreaded environment, a thread may observe a shared field 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:
class ExampleClientCode {

  private final USCurrency currency = new USCurrency();
  
// ...

  public ExampleClientCode() {

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

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

    //...
  }
}

 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. Compliant Solution

This compliant solution uses the variant of the Builder pattern \[[Gamma 95|AA. Java References#Gamma 95]\] suggested by Bloch \[[Bloch 08|AA. Java References#Bloch 08]\] to ensure thread safety and atomicity of object creation. 

{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;

    privatepublic 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:
class ExampleClientCode static public Builder GetBuilder() {

  private volatile return new Builder()USCurrency currency;
  }  
}

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

// ...

  public ExampleClientCode() {

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

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

    //...
  }
}
The {{GetBuilder