Page History

While the methods used in method chaining can be atomic, the chain they comprise is inherently non-atomic. Consequently, methods that are involved in method chaining should not be invoked concurrently unless the caller provides sufficient locking as illustrated in guideline [VNA03-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, if accessed concurrently, a thread may observe shared fields to contain inconsistent values. This noncompliant code example shows the JavaBeans pattern, which is not thread-safe.

{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
    //...
  }
}

h2. Compliant Solution

This compliant solution uses the variant of the Builder pattern \[[Gamma 1995|AA. Java References#Gamma 95]\] suggested by Bloch \[[Bloch 2008|AA. Java References#Bloch 08]\] to ensure the thread safety and atomicity of object creation. {mc} What does this mean? It can be accessible to any number of threads ~DM => The method chaining is actually constrained to the {{USCurrency.Builder}} class which is only accessible from a single thread. {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:
class ExampleClientCode  {

  private volatile USCurrency currency;
  // ...

  public ExampleClientCode() {

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

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

    //...
  }
}