Decoration is the name of a popular design pattern. Using decoration, an existing object's behavior can be extended without changing the implementation of the object.

...

Service Decoration Methods

package org.example.myapp.services;

import org.apache.tapestry5.ioc.services.LoggingDecorator;
import org.slf4j.Logger;

public class MyAppModule
{
  public static Indexer build()
  {
    return new IndexerImpl();
  }

  public static <T> T decorateIndexer(Class<T> serviceInterface, T delegate,
    String serviceId, Logger logger,

    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }
}

The method decorateIndexer() is a service decorator method because it starts with the word "decorate". In this simple case, only the myapp.Indexer service will be decorated, even if there are other services in this module or others ... this is because of the name match ("decorateIndexer" and "buildIndexer"), but we'll shortly see how annotations can be used to target many services for decoration.

...

Alternately, when targetting services whose type is known at compile time, you may provide a parameter whose type matches the service interface. For example, decorateIndexer() will always be applied to the Indexer service, whose type (Indexer) is known. We could therefore rewrite decorateIndexer() as:

  public static Indexer decorateIndexer(Indexer delegate, Logger logger, LoggingDecorator decorator)
  {
    return decorator.build(Indexer.class, delegate, "Indexer", logger);
  }

Of course, nothing stops you from combining building with decorating inside the service builder method:

package org.example.myapp.services;

import org.apache.tapestry5.ioc.services.LoggingDecorator;
import org.slf4j.Logger;

public class MyAppModule
{
  public static Indexer build(Logger logger, LoggingDecorator decorator)
  {
    return decorator.build(Indexer.class, logger, new IndexerImpl());
  }
}

But as we'll see next, it's possible to have a single decorator method work on many different services by using annotations.

...

For example, to target all the services in your module:

  @Match("*")
  public static <T> T decorateLogging(Class<T> serviceInterface, T delegate,
    String serviceId, Logger logger,
    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }   

You can use multiple patterns with @Match, in which case, the decorator will be applied to a service that matches any of the patterns. For instance, if you only wanted logging for your data access and business logic services, you might end up with @Match("Data*", "*Logic") (based, of course, on how you name your services).

...

This annotation allows any number of ordering constraints to be specified for the decorator, to order it relative to any other decorators.

For example, you almost always want logging decorators to come first, so:

  @Match("*")
  @Order("before:*")
  public static <T> T decorateLogging(Class<T> serviceInterface, T delegate,
    String serviceId, Logger logger,
    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }   

"before:*" indicates that this decorator should come before any decorator in any module.

...

  @Decorate
  @Match("*DAO")
  public static <T> T byServiceId(Class<T> serviceInterface, T delegate,
    String serviceId, Logger logger,
    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }

The decorator above is applied to any service whose id matches the "*DAO" pattern.

Alternatively, marker annotations can be placed on the decorate method to match a specific service.

  @Decorate
  @Blue
  public static <T> T byMarkerAnnotation(Class<T> serviceInterface, T delegate,
    String serviceId, Logger logger,
    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }

The decorator above is applied to any service that is marked by the @Blue annotation.

By default, @Decorate annotation applies the decorator to any service matched by the @Match or marker annotations. You can limit the matching to a single service interface, as shown in the following example.

  @Decorate(serviceInterface=MyService.class)
  @Match("*DAO")
  public static <T> T byServiceId(Class<T> serviceInterface, T delegate,
    String serviceId, Logger logger,
    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }

In the example above, the decorator is applied to any implementation of MyService interfaces whose id matches the "*DAO" pattern.

  @Decorate(serviceInterface=MyService.class)
  @Blue
  public static <T> T byMarkerAnnotation(Class<T> serviceInterface, T delegate,

...

    String serviceId, Logger logger,
    LoggingDecorator decorator)
  {
    return decorator.build(serviceInterface, delegate, serviceId, logger);
  }

The decorator above is applied to any implementation of the MyService interface that is marked by the @Blue annotation.

...

By way of an example, we'll show an implementation of the LoggingDecorator service:

public class LoggingDecoratorImpl implements LoggingDecorator
{
    private final AspectDecorator aspectDecorator;

    private final ExceptionTracker exceptionTracker;

...

    public LoggingDecoratorImpl(AspectDecorator aspectDecorator, ExceptionTracker exceptionTracker)
    {
        this.aspectDecorator = aspectDecorator;
        this.exceptionTracker = exceptionTracker;
    }

    public <T> T build(Class<T> serviceInterface, T delegate, String serviceId, final Logger logger)
    {
        final ServiceLogger serviceLogger = new ServiceLogger(logger, exceptionTracker);

        MethodAdvice advice = new MethodAdvice()
        {
            public void advise(Invocation invocation)
            {
                boolean debug = logger.isDebugEnabled();

                if (debug) serviceLogger.entry(invocation);

...

                try
                {
                    invocation.proceed();

...

                }
                catch (RuntimeException ex)
                {
                    if (debug) serviceLogger.fail(invocation, ex);

                    throw

...

 ex;
                }

                if (!debug) return;

                if (invocation.isFail())

...

                {
                    Exception thrown = invocation.getThrown(Exception.class);

...

                    serviceLogger.fail(invocation, thrown);

                    return;
                }

                serviceLogger.exit(invocation);
            }
        };

        return aspectDecorator.build(serviceInterface, delegate, advice,
                                      String.format("<Logging interceptor for %s(%s)>", serviceId,
                                                    serviceInterface.getName()));
    }
}

The actual code has been refactored slightly since this documentation was written.

...

The AspectDecorator service can also be used in more complicated ways: it is possible to only advise some of the methods and not others, or use different advice for different methods. Check the JavaDoc for more details.