In 1985 I had a summer job developing mainframe-based business applications in APL. For those who don't remember APL, it was a very terse language, requiring a special keyboard with all sorts of weird symbols, but it offered some extremely powerful mechanisms for manipulating data stored in arrays. As an example, Conway's "Life" cellular automata game can be implemented in 30-40 characters of APL code, and a program to find all prime numbers below a certain number could be written in 20 characters. (To the uninitiated, such an APL program pretty much looks like line noise.) APL jocks liked to joke that any program could be written in one line in APL. (Reading such a program, on the other hand, was not as easy.)

Macho competition and obfuscated programming contests aside, in what situations is it valuable, from a software engineering perspective, to be able to perform an arbitrary sequence of operations on an object in a single expression? In the Java™ language, several cases exist where being able to instantiate and initialize a complex object in a single expression can improve the code's readability (field initializers, method parameters). There is even one situation where it is downright inconvenient if instantiation and initialization cannot be completed in a single expression (using constructor arguments to instantiate a new object and then passing the new object to a super() or this() constructor).

Mutability: Yes, no, and sometimes

Some objects are immutable (meaning that once constructed, their state does not change), whereas others are mutable. For some immutable objects, immutability is guaranteed by the classes' implementation (such as the String class); for others, immutability is simply assumed by convention, specification, or documentation. (The virtues of immutable objects -- simplicity, safety, thread-safety -- have been extolled in this column and elsewhere, so I won't belabor them here.) Whether immutability is enforced or simply a convention for a given object, the behavior is the same -- once the object is initialized, its state is not modified again.

Some entities can be sensibly modeled as either mutable or immutable objects. The String class is immutable, but that was simply one sensible way to implement a string class. (The C++ STL implements a mutable string class, which is another sensible way to implement String.) Other objects can only be mutable -- for example, it would make no sense for a counter to be immutable. Strictly defined, a mutable object is any object whose state can be changed in an observable way after construction. But by defining mutability only in terms of whether state might ever change, we can miss out on some important object lifecycle distinctions.

Mutability lifecycles

Some objects are mutated throughout their lifecycle -- such as counters or other status-holding objects. Others are initialized to a desired state, perhaps through a series of calls to setters or other mutative methods, and then not modified again until they are garbage collected. Strictly speaking, such objects are mutable, because their state was not set entirely in the constructor and can be mutated, but from the perspective of the program that uses them, they might as well be immutable. Take, for instance, a Properties object that is used by an application to hold the contents of a properties file for configuration purposes. Early in the application, the Properties object is instantiated and loaded with values from the file, but thereafter, it is not modified again. The lifecycle of this Properties object has two phases -- a phase where it is being initialized (treated as mutable) and a phase where it is being used (treated as immutable). Typically, a Properties object used in this manner is not published to the rest of the application until the first phase is complete. So, from the perspective of the rest of the application, the Properties object might as well be immutable.

This phase-change behavior is quite common. Some classes, such as SimpleDateFormat, tend to be used in such a two-phase manner almost exclusively -- once the formatting options are set, the formatter may be used many times, but the settings tend not to be changed after the formatter is "fully initialized." Other classes, such as Properties or HashMap, are sometimes used in this two-phase manner, but frequently treated as fully mutable objects as well. No established name exists to refer to objects that have this two-phase lifecycle, so I'm going to make one up: immutable-once-initialized (IOI). IOI objects generally have a lifecycle that goes something like: construct-modify-modify-modify-publish-use-use-use.

Back to top

The self-return idiom

API designers can make life easier for programmers by anticipating when an object might be used in an IOI manner, and in those situations, using the "self-return idiom" to facilitate easier initialization. The self-returning idiom involves having mutator methods (setXyz() and appendFoo()) return the this reference after performing their action. The StringBuffer class illustrates the self-return idiom -- all the append() methods return a reference to the StringBuffer itself after updating the state of the internal buffer, as shown in Listing 1:

public StringBuffer append(String str) {
    // append str to the internal buffer
    return this;
}

The benefit of the self-return idiom is that it enables you to chain multiple calls together, rather than writing them each out as separate statements:

stringBuffer.append("a=").append(a)
    .append("; b=").append(b);

This code is more readable and more compact than the alternative, which involves four statements. Using the self-return idiom generally has little negative effect on the API design, as many mutative methods (setters, add() and append()) do not return a value anyway, but it can make life a lot easier for your callers. It's too bad more classes don't follow StringBuffer's lead -- it could make some classes a lot more convenient to use.

Static initialization

How many times have you wanted to statically initialize a Set with several known values, but not intended your program to modify the Set? Using the existing Collections classes, this approach would require a static initializer block, and for the collection to be initialized in a different place than it is constructed. Let's say you wanted to pre-initialize a Set with some regular expression patterns you are going to search for in a document. Using the existing API, you would have to do it like Listing 2:

private static Set<Pattern> patternSet = new HashSet<Pattern>();
static {
    s.add(Pattern.compile("\b(roast beef)\b"));
    s.add(Pattern.compile("\b(on rye)\b"));
    s.add(Pattern.compile("\b(with mustard)\b"));
}

Granted, writing a static initializer and putting it near the object's declaration is not a terrible hardship, but it is somewhat annoying, and the more that initialization and declaration are separated, the greater the chance that future modifications will subvert an intended invariant. Further, if you want to make patternSet immutable from the perspective of your program (a good practice, because it prevents subtle coding errors), you would have to instantiate a temporary Set in the static initializer block, wrap it with Collections.unmodifiableSet(), and then stuff the wrapped set back into patternSet.

In this case, it would have been nice if the Collections classes used the self-return idiom, because then we could have constructed and initialized the Set all in one place. But we can still build an adapter that does what we want. Listing 3 shows an adapter class that simplifies the process of initializing a Set:

public class SetAdapter<T> implements Set<T> {
    private final Set<T> s; 
    public SelfReturnSetAdapter(Set<T> s) { this.s = s; }

    public Set<T> append(T t) { s.add(t); return this; }
    public Set<T> unmodifiableSet() { return Collections.unmodifiableSet(s); }

    // delegate other Set methods to s
}

Now, using SetAdapter, we can initialize the set of patterns more easily, and without separating the initialization of the set from the initialization of the variable. As an added bonus, we can easily "close" the set by having the last call wrap the set with an unmodifiable wrapper, and still make the patternSet variable final without introducing temporary variables. The only loss of transparency is that we cannot override the add() method to return a value, so we have to give our mutative methods different names, such as append(). Listing 4 shows patternSet initialized inline with SetAdapter instead of with a static initializer block:

private final static Set<Pattern> patternSet 
    = new SetAdapter(new HashSet<Pattern>())
          .append(Pattern.compile("\b(roast beef)\b"))
          .append(Pattern.compile("\b(on rye)\b"))
          .append(Pattern.compile("\b(with mustard)\b"))
          .unmodifiableSet();

Instantiating DOM documents

If the designers of the DOM API understood this concept, building representations of XML documents would be a lot easier. (Sure, criticizing the DOM APIs is a bit like shooting fish in a barrel.) Suppose we want to build the following XML document, representing an article and its embedded links:

<article title="Flossing Penguins - A Dentist's Journey to the Pole"
       author="Jeremy Stringfellow, DMD"
       url="http://www.penguinfloss.com/travel/stringfellow.html">
   <link anchor="Glide Floss" url="http://www.crest.com/glide/index.jsp" />
   <link anchor="Antarctica Facts" url="http://www.cia.gov/cia/publications/factbook/geos/ay.html" />
</article>

Constructing this document with DOM would be an exercise in annoyance, involving many temporary variables. We must create a document, an article element, and two link elements, add the attributes to them, and attach the elements to their parents. Unfortunately, each of these operations must be a separate statement, as shown in Listing 5:

Document document = documentFactory.newDocument();
Element articleElement = document.createElement("article");
articleElement.setAttribute("title", article.getTitle());
articleElement.setAttribute("author", article.getAuthor());
articleElement.setAttribute("url", article.getURL());
        
Element linkElement = document.createElement("link");
linkElement.setAttribute("anchor", link.getAnchor());
linkElement.setAttribute("url", link.getURL());
articleElement.appendChild(linkElement);
        
linkElement = document.createElement("link");
linkElement.setAttribute("anchor", anotherLink.getAnchor());
linkElement.setAttribute("url", anotherLink.getURL());
articleElement.appendChild(linkElement);
        
document.appendChild(articleElement);

Now, suppose the DOM classes supported the self-return idiom for setAttribute() and appendChild(). Each element could be created complete in a single expression, and several temporaries could be eliminated. As a bonus, it is even possible to make the structure of the code look like the structure of the resulting document, as shown in Listing 6:

document.appendChild(
    document.createElement("article")
        .setAttribute("title", article.getTitle())
        .setAttribute("author", article.getAuthor())
        .setAttribute("url", article.getURL())
        .appendChild(
            document.createElement("link")
                .setAttribute("anchor", link.getAnchor())
                .setAttribute("url", link.getURL()))
        .appendChild(
            document.createElement("link")
                .setAttribute("anchor", anotherLink.getAnchor())
                .setAttribute("url", anotherLink.getURL())));

While there isn't all that much less code here, were the API to work this way, entire DOM Elements could be instantiated and initialized in a single statement, which would make it slightly easier (and clearer) to create methods that return DOM Elements, or to initialize DOM Elements in variable initializers. And note that without the self-return idiom, it is impossible to pass a complete DOM Element to a super() or this() constructor without writing a helper function, because the DOM API makes it impossible to build an element in a single statement and the super() or this() constructor must be the first statement in a constructor.

Back to top

Harnessing laziness

The self-return idiom can sometimes improve the readability of code, and enables you to completely initialize a logical entity in a single expression, meaning that you can eliminate temporary variables and helper functions when initializing fields or passing arguments to super() and this() constructors. But there is another benefit of the self-return idiom, which comes from co-opting laziness. By reducing the amount of work involved in using a given API, you increase the likelihood that the API will be used properly and effectively. API designers often do not give this aspect sufficient consideration -- that in many situations a developer is faced with a choice of "doing it right" or "doing it well enough." API designers should encourage developers to do things right by making APIs so easy to use that laziness will not discourage developers from using them. (DOM API designers clearly did not understand this lesson.) When designing an API, you should look for use cases where objects might be created in an IOI manner, and provide appropriate methods for building such objects easily - preferably offering users the opportunity to build them in a single expression so that they can be used in initializers or superclass constructor arguments. Similarly, think about the expected role of setters. Are they truly accessors for updating the state of mutable objects, or are they likely to be used as part of an extended construction process, as in SimpleDateFormat? If the latter, it costs nothing to have them return the this reference.

On the subject of laziness, how often do you give your classes a useful toString() implementation (before being forced to for debugging)? Writing a good toString() is certainly not hard, but laziness often prevents these methods from being written, or from updating then when fields are added to a class. Truth be told, they are annoying to write and modify, involving long string concatenations.

Listing 7 shows a simple utility class, which is a crutch for writing toString() implementations. It is a trivial class, built atop StringBuffer, which allows you to build up the toString() value, appending state variables as you go, in a single expression, using the self-return idiom.

public class ToString {
    private StringBuffer sb = new StringBuffer();

    public ToString(String title) { sb.append(title).append(" "); }
    public ToString(Object o) {     this(o.getClass().getName()); }

    public ToString add(String name, String value) {
        sb.append(name).append("=\"").append(value).append("\" ");
        return this;
    }

    public ToString add(String name, Object value) {
        return add(name, value == null? "null" : value.toString());
    }

    public ToString add(String name, int value) {
        sb.append(name).append("=").append(value).append(" ");
        return this;
    }
    // name-value versions for other primitive types  

    public ToString addGroup(String name, String value) {
        sb.append(name).append("={").append(value).append("} ");
        return this;
    }

    public ToString add(String name, String[] value) {
        sb.append(name).append("=[");
        for (int i = 0; i < value.length; i++) 
            sb.append("\"").append(value[i]).append("\" ");
        sb.append("] ");
        return this;
    }

    public String toString() {
        return sb.toString();
    }
}

While the resulting toString() code is again not all that different from the by-hand implementation, it is slightly easier to read and edit (especially with IDEs such as Eclipse). The benefit is not that you save a few seconds writing toString() -- it is that laziness is less likely to inhibit the creation of a toString() method at all. Listing 8 shows a typical toString() method using both the by-hand approach and the ToString approach. (The ToString class can also be used independently of the toString() method for producing informative, structured strings to write as log messages.)

// by hand
public String toString() {
    return "Address " 
        + "streetAddress=" + streetAddress + " "
        + "city=" + city + " " + "state=" + state + " "
        + "zipCode=" + zipCode + " ";
}


// with ToString
public String toString() {
    return new ToString("Address")
        .add("StreetAddress", streetAddress)
        .add("city", city).add("state", state)
        .add("zipCode", zipCode)
        .toString();
}

Back to top

Conclusion

The self-return idiom is not a particularly deep or revolutionary technique, but it can offer an incremental improvement to the usability of an API. When objects are used in an immutable-once-initialized manner, it is extremely convenient to be able to declare and initialize them in a single statement or expression. While it is possible to work around the limitations of a class that does not permit initialization atomicity through initializer blocks and helper functions, the readability of the code can suffer, and often needlessly so. When writing APIs, think about the likely mutability lifecycle of the object, and consider whether the self-return idiom might make life easier for your callers.

Resources

• Take a look at what the APL keyboard looked like.
  
  
• Check out these compact APL programs to compute prime numbers and Conway's Life game.
  
  
• Bill Venners' books in progress, People-oriented API Design and API Design with Java, discuss many facets of designing APIs.
  
  
• To learn more about Java technology, visit the developerWorks Java zone. You'll find technical documentation, how-to articles, education, downloads, product information, and more.
  
  
• Visit the New to Java technology site for the latest resources to help you get started with Java programming.
  
  
• Get involved in the developerWorks community by participating in developerWorks blogs.
  
  
• Browse for books on these and other technical topics.
  
  

About the author

Rate this article

Comments

Back to top

Table of contents

• Mutability: Yes, no, and sometimes
• The self-return idiom
• Harnessing laziness
• Conclusion
• Resources
• About the author
• Comments