Decorator Classes

Suppose that this is not your intent and that you want the iterator method to give read-only access to the bank accounts. Two issues need to be addressed. First, the iterator method gives the client complete access to each BankAccount object; you want it to deny access to the modification methods of BankAccount. Second, iterators have the method remove, which deletes the object currently being examined; you want to ensure that clients cannot call this method. The solution to both issues is to use wrapping.

Let’s pause for a moment to look at how these changes affect the banking demo. The iterator returned by the bank’s iterator method is an unmodifiable iterator of unmodifiable BankAccount objects. However, from the client’s point of view nothing has changed. The client still sees an iterator of BankAccount objects. Consequently, classes such as IteratorAccountStats do not need to be modified.

What makes this feat possible is that the wrapper classes UnmodifiableAccount and UnmodifiableBankIterator implement the same interface as the objects that they wrap. This feature enables the wrapped objects to be used in place of the unwrapped objects. Such a wrapper is called a decorator.

The purpose of a decorator is to change the behavior of one or more methods of a class without changing its interface. The behavioral changes are the “decorations” to the class.

Listing 8-6 omits several methods from the BankAccount interface. As in Listing 8-3, the code for these omitted methods are similar to getAcctNum—they simply call the corresponding method of the wrapped object.

The Decorator Pattern

BankAccountWrapper implements each BankAccount method by calling the corresponding method of its wrapped object. By itself, this class does nothing. Its value is that it simplifies the writing of other BankAccount wrapper classes. This explains why BankAccountWrapper is an abstract class even though it has no abstract methods. It depends on subclasses to override its methods with interesting behavior.

A class diagram for the BankAccount classes appears in Figure 8-1. The decorator classes are shaded. Their dependency on BankAccount is held by BankAccountWrapper .

The decorator classes in this class diagram are organized according to the decorator pattern. The decorator pattern asserts that the decorations for an interface form a hierarchy. The root of the hierarchy is an abstract wrapper class that holds a reference to its wrapped class and provides default implementations of the interface methods. The decorator classes are the subclasses of the wrapper class. The nondecorator classes of the interface are called its base classes. Figure 8-2 depicts the class diagram for the decorator pattern.

A decorator class, like an adapter, can be thought of as transforming an input object into an output object. The difference is that the output of a decorator has the same type as its input. This feature means that decorators can be composed.

For example, consider the banking demo. The Bank class holds a map of BankAccount objects. Some of them will be undecorated and some will be decorated with SuspiciousAccount. If a client calls the bank’s iterator method then all objects in the iterator will be decorated with UnmodifiableAccount. This implies that the suspicious accounts will now have two decorations.

Although x, y, and z are different BankAccount objects, they each refer to account 5. Objects y and z are just different decorations of that account.

The fourth statement in Listing 8-11 sets the variable a to 5. The next statement also sets variable b to 5 because y.getAcctNum calls x.getAcctNum. Similarly, variable c also gets set to 5 because z.getAcctNum calls y.getAcctNum which calls x.getAcctNum.

The call to x.deposit increases x’s balance by 4. The call to y.deposit increases x’s balance by another 4, because y.deposit calls x.deposit. It also writes a message to the console because y is suspicious. Listing 8-11 deliberately does not call z.deposit because that call would throw an exception due to the fact that z is unmodifiable.

Figure 8-3 depicts the memory contents of these variables after the code has executed. Each variable’s rectangle shows the value of its state variables. An AbstractBankAccount object has three state variables: acctnum, balance, and owner. For simplicity, this figure does not show the object that owner refers to. A BankAccountWrapper object has one state variable, ba, which references the object being wrapped.

Figure 8-3 illustrates how a decorated object can be thought of as a chain of objects. The head of the chain is the most recent decoration. The tail of the chain is the undecorated version of the object. When a method is called, the method execution starts at the head of the chain and proceeds down the chain.

This situation is a form of recursion. The decorator classes are the recursive classes. A method call can be thought of as recursively traversing the chain of decorators. For example, z.getAcctNum recursively calls y.getAcctNum, which recursively calls x.getAcctNum, which returns its value.

The Chain of Command Pattern

The chain of command pattern is a special case of the decorator pattern where the decorators perform tasks instead of calculating values. Each decorator understands some part of the task. A request to perform the task is sent to the first decorator in the chain and is passed down the chain until it encounters a decorator that can perform that task. If no decorator is able to perform the task then the base class performs a default action.

These criteria are obviously a simplified version of what a real bank would use. But the point is that loan approval requires the coordination of very different kinds of data—such as customer history, financial creditworthiness, and assets—that are often the responsibility of different departments. You could combine these criteria into a single method but then the entire method would need to be modified if any of the criteria changed. The Single Responsibility rule suggests that a better design is to create a separate class for each kind of criterion. These separate classes can then be implemented as decorators and organized according to the chain of command pattern. Figure 8-4 illustrates this organization. The interface is LoanAuthorizer, which has the method authorizeLoan. The classes GoodCustomerAuthorizer, CreditScoreAuthorizer, and CollateralAuthorizer implement each of the three criteria.

Decorated Iterators

The end of Chapter 6 discussed collection streams and how their filter and map methods transform one stream to another. You can use decorators to do something similar with iterators. In particular, you can create decorator classes MapIterator and FilterIterator that transform one iterator into another one. MapIterator transforms the value of each element in its component iterator, returning an iterator of those transformed values. FilterIterator filters its component iterator, returning an iterator containing the elements that satisfy the given predicate.

In the first example, the iterator denoted by variable i1 contains the four strings {“a,” “bb,” “ccc,” “dddd”}. The iterator i2 restricts i1 to strings that are more than one character long, that is {“bb,” “ccc,” “dddd”}. Iterator i3 restricts i2 to strings that are less than four characters long, that is {“bb,” “ccc”}. Iterator i4 converts those values to uppercase, that is {“BB,” “CCC”}. The code then uses the standard idiom to traverse i4 and print its elements.

The second example is similar. Iterator j4 contains the lengths of those strings whose length is between two and three. The code traverses j4 to find the maximum length and prints it.

These decorated iterators are remarkably efficient. This efficiency stems from the fact that the FilterIterator and MapIterator objects do not pre-calculate their values. Instead, they get their values on demand by querying their component iterators. Note that each decorator class traverses its component iterator once. Consequently, traversing any decorated iterator will traverse its base iterator exactly once, no matter how many decorations it has!

For an example, consider iterator i4 in Listing 8-19. The loop that prints its elements requires just a single pass through the underlying collection of strings. The sequence diagram shown in Figure 8-5 can help to clarify this fact. This diagram displays the four communicating iterators of Listing 8-19, one per column. The rows denote a timeline of the method calls between these iterators.

This diagram shows the sequence of calls required to retrieve the first value from iterator i4. The main method begins by calling hasNext at step 1 and receives the return value true at step 16. It then calls next at step 17 and receives “BB” at step 20.

The behavior of each iterator can be observed by following the sequence of arrows attached to its column. The behavior of i2 is especially interesting. In order to respond to the hasNext method, it needs to repeatedly call i1.next() until i1 returns a value that satisfies i2’s predicate. The diagram shows that the first value returned, “a,” did not satisfy the predicate, but the second value “bb” did.

As an aside, you might have noticed that FilterIterator and MapIterator do not have a common abstract wrapper class and thus do not strictly conform to the decorator pattern. MapIterator is the culprit because it wraps an object of type Iterator<T> but implements Iterator<R>. Since the elements of the mapped iterator have a different type from its component iterator, there is no way to choose a type for the common wrapper class.

Implementing Collection Streams

The FilterIterator class transforms an iterator into another iterator that generates a subset of its elements. This transformation is reminiscent of the filter method of the Stream interface from Listing 6-35. Similarly, the MapIterator class is reminiscent of the map method of Stream. This resemblance is not coincidental. This section shows how decorated iterators form the foundation of Stream implementations.

The Java library implementation of the Stream classes is to be commended for its encapsulation. However, this encapsulation makes it difficult to study the techniques used to implement streams. Consequently, I have written a stripped-down version of Stream, called SimpleStream. The class SimpleStream contains five of the methods described in Chapter 6: iterator, forEach, filter, map, and reduce. SimpleStream differs from Stream in that it is a class, not an interface. It has a single constructor, whose argument is an iterator.

The efficiency of the decorated iterators carries over to the SimpleStream methods . The filter and map methods construct a new decorated iterator and do not perform any traversal. The forEach and reduce methods traverse the wrapped decorated iterator, which will always entail just a single iteration through the underlying collection.

Decorated Input Streams

Decorators also play a prominent role in the Java byte-stream classes (which, you should recall, are completely unrelated to the collection streams of the previous section). Consider again the abstract class InputStream. This class was discussed in Chapter 3, along with its subclasses FileInputStream, PipedInputStream, and ByteArrayInputStream. This chapter examines some of the decorator subclasses of InputStream.

The class FilterInputStream is the abstract InputStream wrapper . Three of its decorator subclasses are BufferedInputStream, ProgressMonitorInputStream, and CipherInputStream. Figure 8-6 gives the corresponding class diagram. Note how it conforms to the decorator pattern. The following subsections discuss these FilterInputStream subclasses.

Progress Monitoring

Another InputStream decorator subclass is ProgressMonitorInputStream . This decorator does not affect how the bytes are read. Instead, its “decoration” is to display a window containing a progress bar. Listing 8-29 gives code for the class ProgressMonitorFileRead, which uses a ProgressMonitorInputStream to decorate a FileInputStream.

public class ProgressMonitorFileRead {

   public static void main(String[] args) throws IOException {

      String src = "mobydick.txt";

      String msg = "reading " + src;

      try (InputStream  is = new FileInputStream(src);

           InputStream pis = new ProgressMonitorInputStream(

                                 null, msg, is)) {

         int x = pis.read();

         while (x >= 0) {

            byte b = (byte) x;

            // process b ...

            x = pis.read();

         }

      }

   }

}

Listing 8-29

The ProgressMonitorFileRead Class

The ProgressMonitorInputStream constructor has three arguments. The first is a pointer to the parent window of the progress monitor window. The value is null in Listing 8-29 because the program is not running in a GUI environment. The second argument is the label to be displayed with the progress bar. In this example the label is “reading mobydick.txt.” The third is a reference to the input stream being decorated. Figure 8-7 displays a screenshot of the progress monitor window from my computer.

The ProgressMonitorInputStream decorator is responsible for monitoring the progress of reading its wrapped input stream and displaying a progress bar if warranted. Its constructor calls the available method of the wrapped stream, which returns its best guess as to the total number of bytes remaining in the stream. Each call to read repeats the call to available and compares its current value to the initial value. If that ratio is sufficiently high, it redisplays the progress window.

Decorator Transparency

Another way that a decorator class can enhance the functionality of its component object is to implement new methods. For example, the decorator classes PushbackInputStream and PushbackReader implement the method unread. This method puts a specified byte (or character) onto the input stream so that the next call to read will return it before continuing with the rest of the stream.

The unread method is not defined in Reader. Consequently, the variable pr in Listing 8-31 must have the type PushbackReader.  (If it had the type Reader, then its call to unread would not compile.) The helper method skipWhitespace is therefore not transparent because it needs to know that the reader being passed to it is a pushback reader.

For another example of decorator classes that implement new methods, consider again BufferedInputStream and BufferedReader. These classes implement two methods for rereading portions of a stream: the method mark, which marks a location in the stream; and the method reset, which repositions the stream at the marked location.

For an example use of these methods, consider the following task: given a text file and an integer N, write a program DoubledChars that finds a character that appears twice in the file separated by N characters. For example, if N=0 then the program is looking for doubled characters in the text, as in “...aa...”; if N=1 then the program is looking for doubled characters with one character in between, as in “...aba...”.

Many Reader classes (such as FileReader) are only able to read their characters once, and so they cannot implement mark and reset. However, the decorator class BufferedReader can use its buffer to get around this limitation. A call to its mark method sets the “mark location” to be the current position in the buffer and a call to reset sets the buffer position back to the saved mark location. Consequently, when characters are reread following a reset, they will be taken from the buffer and not the underlying reader. The argument to the mark method specifies the maximum size of the buffer array. Without this limit, the buffer array could become too large and generate unintended memory exceptions.

Note that the argument to the check method in Listing 8-32 has the type Reader and not BufferedReader. That is, the check method is transparent. This transparency is possible because mark and reset are defined by Reader.

But how can that be, given that some readers (such as file readers) do not support mark and reset? The answer is that all readers must have mark and reset methods; it is just that many of those methods throw an exception if called. This possibility of throwing an exception is the price the Java designers paid for achieving transparency.

The Java library has the method markSupported to help clients avoid these exceptions. If a class can implement the mark and reset methods then a call to markSupported returns true. If a class cannot implement them then markSupported returns false and the mark and reset methods throw exceptions. A client can call markSupported if it has any doubts about whether a reader supports the methods.

Let’s stop to review the design implications of PushbackReader and BufferedReader. Although both decorator classes implement new methods, the Java library treats them very differently. The PushbackReader method unread is not recognized by Reader, and clients that use the method must do so non-transparently. On the other hand, the BufferedReader methods mark and reset are part of Reader, and clients can call the methods transparently. The downside to this transparency is that a client must be careful to avoid generating exceptions.

These two design decisions can be summarized as a choice between transparency and safety. There is no general rule that a designer can use to make this choice; you have to consider each situation individually.

The Java library usually opts for safety. A big reason why the library chose transparency for mark and reset is that those methods are also supported by some of the nondecorator base classes, such as ByteArrayInputStream , CharArrayReader, and StringReader. Each of these classes store the stream in an underlying array. In effect, their values are already buffered, so mark and reset are easily implemented. Since mark and reset are supported by multiple classes, the designers likely decided that they deserved inclusion in the InputStream API.

The class PushbackInputStream does not support mark and reset, even if its underlying input stream does. Thus variable pis will support unread but not mark and reset. On the other hand, if you interchange the declarations of bis and pis then bis will support mark and reset but not unread. In fact, there is no way for an input stream (or reader) to support mark, reset, and unread.

The class ProgressMonitorInputStream , unlike PushbackInputStream, supports mark and reset when its underlying input stream does. Thus variable pmis supports mark and reset. Interchanging the declarations of bis and pmis does not change the functionality of the decorated input stream.

The problem is that ProgressMonitorInputStream calls the available method of its underlying stream, which tells it how many bytes remain. But CipherInputStream cannot accurately know how many characters will result from its encoding, so its available method always returns 0. Thus, pmis believes that the reading has finished and will not display the monitor window.

The lesson here is that decorator transparency is an elusive goal. At first glance the enhancements provided by the input stream decorators seem to be independent of each other, but they interact in subtle ways. If a programmer is not aware of these interactions then “mysterious” bugs are likely to occur. The more that a designer can approach decorator transparency, the easier it will be for the users of these classes.

Summary

A decorator class is a wrapper that implements the same interface as the class that it wraps. The purpose of this wrapping is to alter the functionality of the wrapped object, either by enhancing the behavior of its existing methods or providing new ones. Decorators embrace the spirit of the Open/Closed rule—by decorating a class, you can change how the class works without having to make any modifications to it.

The decorator pattern indicates how to organize the decorators for a given interface. All decorators should have a common abstract superclass to manage the wrapping and provide default implementations of the interface methods. Each decorator class will extend this common superclass and provide implementations of the methods that it wishes to enhance. The chain of command pattern is a special instance of the decorator pattern in which the decorators perform tasks instead of calculate values.

When designing decorator classes, you must consider the issue of transparency. Ideally, a client should be able to use an InputStream or Reader object without knowing its class, and should be able to compose decorators without having to consider their possible interactions. A designer must recognize the possibility of conflict between different decorators so as to better analyze the tradeoffs involved.