• A Common Situation:
  • A method is invoked on the value returned by another method, without assigning the returned value to an intermediate variable
• The Idea:
  • You should consider this when writing methods

• An Example:
  • You need to construct an email address
• One Implementation:
  • javaexamples/programmingpatterns/chainedmutators/InvocationChaining.java (Fragment: sbintermediate)

            StringBuilder sb = new StringBuilder();
            sb.append(user);
            sb.append("@");
            sb.append(university);
            sb.append(".edu");
            

• An Observation:
  • This is messier than String concatenation
• Using Invocation Chaining:
  • javaexamples/programmingpatterns/chainedmutators/InvocationChaining.java (Fragment: sbchain)

            StringBuilder sb = new StringBuilder();
            sb.append(user).append("@").append(university).append(".edu");
            

• A Related Example:
  • You are working with a File object that encapsulates the current working directory and you want to know how many characters are in its name
• One Solution:
  • javaexamples/programmingpatterns/chainedmutators/InvocationChaining.java (Fragment: intermediate)

            File   cwd    = new File(".");
            String path   = cwd.getCanonicalPath();
            int    length = path.length();
            

• An Observation:
  • There's no need for the intermediate variable
• Using Invocation Chaining:
  • javaexamples/programmingpatterns/chainedmutators/InvocationChaining.java (Fragment: chain)

            File   cwd    = new File(".");
            int    length = cwd.getCanonicalPath().length();
            

• Why It Works:
  • getCanonicalPath() returns (and evaluates to) a String object that has a length() method

• An Important Difference in the Two Examples:
  • In the path example, the methods do not change the state of their owning objects (i.e., they are accessors not mutators)
• A Question?
  • Why can you use invocation chaining in the email example given that the append() method is a mutator?

• The Idea:
  • Mutators that are to be chained need to return something that a subsequent method can be invoked on
• Specifically:
  • It must return the owning object

javaexamples/programmingpatterns/chainedmutators/Robot.java

/**
 * A simple encapsulation of a Robot that demonstrates
 * how mutators can support invocation chaining.
 *
 * @author  Prof. David Bernstein, James Madison University
 * @version 1.0
 */
public class Robot {
    private int x, y;

    /**
     * Default Constructor.
     */
    public Robot() {
        x = 0;
        y = 0;
    }
    
    /**
     * Move backward one unit.
     *
     * @return A reference to this Robot (so invocations can be chained)
     */
    public Robot moveBackward() {
        y--;
        return this;
    }
    
    /**
     * Move to forward one unit.
     *
     * @return A reference to this Robot (so invocations can be chained)
     */
    public Robot moveForward() {
        y++;
        return this;
    }
    
    /**
     * Move to the left one unit.
     *
     * @return A reference to this Robot (so invocations can be chained)
     */
    public Robot moveLeft() {
        x--;
        return this;
    }
    
    /**
     * Move to the right one unit.
     *
     * @return A reference to this Robot (so invocations can be chained)
     */
    public Robot moveRight() {
        x++;
        return this;
    }

    /**
     * Return a String representation of this Robot.
     *
     * @return  The String representation
     */
    public String toString() {
        return String.format("I am at (%d, %d).", x, y);
    }
}

        

javaexamples/programmingpatterns/chainedmutators/InvocationChaining.java (Fragment: robotchained)

        Robot bender = new Robot();
        bender.moveForward().moveForward().moveRight().moveForward();
        

• The Issue:
  • Documentation is especially important here!
• A Quiz:
  • Some String methods (like toLowerCase()) return a String object. Why? Are String objects mutable?
  • Some StringBuilder methods (like append()) return a StringBuilder object. Why? Are StringBuilder objects mutable?