# Decorator Pattern

version 3.0.3

The Decorator Pattern provides a mechanism to embellish the behaviour of an object without changing its essential interface. A decorated object should be able to be substituted wherever the original (non-decorated) object was expected. Decoration typically does not involve modifying the source code of the original object and decorators should be able to be combined in flexible ways to produce objects with several embellishments.

## 1. Traditional Example

Suppose we have the following `Logger` class.

    class Logger {
        def log(String message) {
            println message
        }
    }

There might be times when it is useful to timestamp a log message, or times when we might want to change the case of the message. We could try to build all of this functionality into our `Logger` class. If we did that, the `Logger` class would start to be very complex. Also, everyone would obtain all of features even when they might not want a small subset of the features. Finally, feature interaction would become quite difficult to control.

To overcome these drawbacks, we instead define two decorator classes. Uses of the `Logger` class are free to embellish their base logger with zero or more decorator classes in whatever order they desire. The classes look like this:

    class TimeStampingLogger extends Logger {
        private Logger logger
        TimeStampingLogger(logger) {
            this.logger = logger
        }
        def log(String message) {
            def now = Calendar.instance
            logger.log("$now.time: $message")
        }
    }

    class UpperLogger extends Logger {
        private Logger logger
        UpperLogger(logger) {
            this.logger = logger
        }
        def log(String message) {
            logger.log(message.toUpperCase())
        }
    }

We can use the decorators like so:

    def logger = new UpperLogger(new TimeStampingLogger(new Logger()))
    logger.log("G'day Mate")
    // => Tue May 22 07:13:50 EST 2007: G'DAY MATE

You can see that we embellish the logger behaviour with both decorators. Because of the order we chose to apply the decorators, our log message comes out capitalised and the timestamp is in normal case. If we swap the order around, let’s see what happens:

    logger = new TimeStampingLogger(new UpperLogger(new Logger()))
    logger.log('Hi There')
    // => TUE MAY 22 07:13:50 EST 2007: HI THERE

Now the timestamp itself has also been changed to be uppercase.

## 2. A touch of dynamic behaviour

Our previous decorators were specific to `Logger` objects. We can use Groovy’s Meta-Object Programming capabilities to create a decorator which is far more general purpose in nature. Consider this class:

    class GenericLowerDecorator {
        private delegate
        GenericLowerDecorator(delegate) {
            this.delegate = delegate
        }
        def invokeMethod(String name, args) {
            def newargs = args.collect { arg ->
                if (arg instanceof String) {
                    return arg.toLowerCase()
                } else {
                    return arg
                }
            }
            delegate.invokeMethod(name, newargs)
        }
    }

It takes any class and decorates it so that any `String` method parameter will automatically be changed to lower case.

    logger = new GenericLowerDecorator(new TimeStampingLogger(new Logger()))
    logger.log('IMPORTANT Message')
    // => Tue May 22 07:27:18 EST 2007: important message

Just be careful with ordering here. The original decorators were restricted to decorating `Logger` objects. This decorator works with any object type, so we can’t swap the ordering around, i.e. this won’t work:

    // Can't mix and match Interface-Oriented and Generic decorators
    // logger = new TimeStampingLogger(new GenericLowerDecorator(new Logger()))

We could overcome this limitation be generating an appropriate Proxy type at runtime but we won’t complicate the example here.

## 3. Runtime behaviour embellishment

You can also consider using the `ExpandoMetaClass` from Groovy 1.1 to dynamically embellish a class with behaviour. This isn’t the normal style of usage of the decorator pattern (it certainly isn’t nearly as flexible) but may help you to achieve similar results in some cases without creating a new class.

Here’s what the code looks like:

    // current mechanism to enable ExpandoMetaClass
    GroovySystem.metaClassRegistry.metaClassCreationHandle = new ExpandoMetaClassCreationHandle()

    def logger = new Logger()
    logger.metaClass.log = { String m -> println 'message: ' + m.toUpperCase() }
    logger.log('x')
    // => message: X

This achieves a similar result to applying a single decorator but we have no way to easily apply and remove embellishments on the fly.

## 4. More dynamic decorating

Suppose we have a calculator class (Actually any class would do).

    class Calc {
        def add(a, b) { a + b }
    }

We might be interested in observing usage of the class over time. If it is buried deep within our codebase, it might be hard to determine when it is being called and with what parameters. Also, it might be hard to know if it is performing well. We can easily make a generic tracing decorator that prints out tracing information whenever any method on the `Calc` class is called and also provide timing information about how long it took to execute. Here is the code for the tracing decorator:

    class TracingDecorator {
        private delegate
        TracingDecorator(delegate) {
            this.delegate = delegate
        }
        def invokeMethod(String name, args) {
            println "Calling $name$args"
            def before = System.currentTimeMillis()
            def result = delegate.invokeMethod(name, args)
            println "Got $result in ${System.currentTimeMillis()-before} ms"
            result
        }
    }

Here is how to use the class in a script:

    def tracedCalc = new TracingDecorator(new Calc())
    assert 15 == tracedCalc.add(3, 12)

And here is what you would see after running this script:

    Calling add{3, 12}
    Got 15 in 31 ms

## 5. Decorating with an Interceptor

The above timing example hooks into the lifecycle of Groovy objects (via `invokeMethod`). This is such an important style performing meta-programming that Groovy has special support for this style of decorating using interceptors.

Groovy even comes with a built-in `TracingInterceptor`. We can extend the built-in class like this:

    class TimingInterceptor extends TracingInterceptor {
        private beforeTime
        def beforeInvoke(object, String methodName, Object[] arguments) {
            super.beforeInvoke(object, methodName, arguments)
            beforeTime = System.currentTimeMillis()
        }
        Object afterInvoke(Object object, String methodName, Object[] arguments, Object result) {
            super.afterInvoke(object, methodName, arguments, result)
            def duration = System.currentTimeMillis() - beforeTime
            writer.write("Duration: $duration ms\\n")
            writer.flush()
            result
        }
    }

Here is an example of using this new class:

    def proxy = ProxyMetaClass.getInstance(Calc)
    proxy.interceptor = new TimingInterceptor()
    proxy.use {
        assert 7 == new Calc().add(1, 6)
    }

And here is the output:

    before Calc.ctor()
    after  Calc.ctor()
    Duration: 0 ms
    before Calc.add(java.lang.Integer, java.lang.Integer)
    after  Calc.add(java.lang.Integer, java.lang.Integer)
    Duration: 2 ms

## 6. Decorating with java.lang.reflect.Proxy

If you are trying to decorate an object (i.e. just a particular instance of the class, not the class generally), then you can use Java’s `java.lang.reflect.Proxy`. Groovy makes working with this easier than just Java. Below is a code sample taken out of a grails project that wraps a `java.sql.Connection` so that it’s close method is a no-op:

    protected Sql getGroovySql() {
        final Connection con = session.connection()
        def invoker = { object, method, args ->
            if (method.name == "close") {
                log.debug("ignoring call to Connection.close() for use by groovy.sql.Sql")
            } else {
                log.trace("delegating $method")
                return con.invokeMethod(method.name, args)
            }
        } as InvocationHandler;
        def proxy = Proxy.newProxyInstance( getClass().getClassLoader(), [Connection] as Class[], invoker )
        return new Sql(proxy)
    }

If there were many methods to intercept, then this approach could be modified to look up closure in a map by method name and invoke it.

## 7. Decorating with Spring

The Spring Framework allows decorators to be applied with interceptors (you may have heard the terms advice or aspect). You can leverage this mechanism from Groovy as well.

First define a class that you want to decorate (we’ll also use an interface as is normal Spring practice):

Here’s the interface:

    interface Calc {
        def add(a, b)
    }

Here’s the class:

    class CalcImpl implements Calc {
        def add(a, b) { a + b }
    }

Now, we define our wiring in a file called `beans.xml` as follows:

    <?xml version="1.0" encoding="UTF-8"?>
    <beans xmlns="http://www.springframework.org/schema/beans"
    	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    	xmlns:lang="http://www.springframework.org/schema/lang"
    	xsi:schemaLocation="
    		http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
    		http://www.springframework.org/schema/lang http://www.springframework.org/schema/lang/spring-lang.xsd">

        <bean id="performanceInterceptor" autowire="no"
              class="org.springframework.aop.interceptor.PerformanceMonitorInterceptor">
            <property name="loggerName" value="performance"/>
        </bean>
        <bean id="calc" class="util.CalcImpl"/>
        <bean class="org.springframework.aop.framework.autoproxy.BeanNameAutoProxyCreator">
            <property name="beanNames" value="calc"/>
            <property name="interceptorNames" value="performanceInterceptor"/>
        </bean>
    </beans>

Now, our script looks like this:

    @Grab('org.springframework:spring-context:3.2.2.RELEASE')
    import org.springframework.context.support.ClassPathXmlApplicationContext

    def ctx = new ClassPathXmlApplicationContext('beans.xml')
    def calc = ctx.getBean('calc')
    println calc.add(3, 25)

And when we run it, we see the results:

    21/05/2007 23:02:35 org.springframework.aop.interceptor.PerformanceMonitorInterceptor invokeUnderTrace
    FINEST: StopWatch 'util.Calc.add': running time (millis) = 16

You may have to adjust your `logging.properties` file for messages at log level `FINEST` to be displayed.

## 8. Asynchronous Decorators using GPars

The following example is inspired by some of the early example code for the Panini programming language. These days, you’ll see this style used with async functions in JavaScript.

    @Grab('org.codehaus.gpars:gpars:0.10')
    import static groovyx.gpars.GParsPool.withPool

    interface Document {
        void print()
        String getText()
    }

    class DocumentImpl implements Document {
        def document
        void print() { println document }
        String getText() { document }
    }

    def words(String text) {
        text.replaceAll('[^a-zA-Z]', ' ').trim().split("\\\\s+")*.toLowerCase()
    }

    def avgWordLength = {
        def words = words(it.text)
        sprintf "Avg Word Length: %4.2f", words*.size().sum() / words.size()
    }
    def modeWord = {
        def wordGroups = words(it.text).groupBy {it}.collectEntries { k, v -> [k, v.size()] }
        def maxSize = wordGroups*.value.max()
        def maxWords = wordGroups.findAll { it.value == maxSize }
        "Mode Word(s): ${maxWords*.key.join(', ')} ($maxSize occurrences)"
    }
    def wordCount = { d -> "Word Count: " + words(d.text).size() }

    def asyncDecorator(Document d, Closure c) {
        ProxyGenerator.INSTANCE.instantiateDelegate([print: {
            withPool {
                def result = c.callAsync(d)
                d.print()
                println result.get()
            }
        }], [Document], d)
    }

    Document d = asyncDecorator(asyncDecorator(asyncDecorator(
            new DocumentImpl(document:"This is the file with the words in it\\n\\t\\nDo you see the words?\\n"),
    //        new DocumentImpl(document: new File('AsyncDecorator.groovy').text),
            wordCount), modeWord), avgWordLength)
    d.print()