Service Advisors

Service advice represents a powerful meta-programming facility available to services. In fact, it is a kind of limited Aspect Oriented Programming.

...

You could track down the implementation of each service and fix the logic that provides a return value ... or you could advise the methods:

  @Match("*")
  public static void adviseNonNull(MethodAdviceReceiver receiver)
  {
    MethodAdvice advice = new MethodAdvice()
    {
      void advise(Invocation invocation)
      {
        invocation.proceed();

        if (invocation.getResultType().equals(String.class) && invocation.getResult() == null)
          invocation.overrideResult("");
      }
    };

    receiver.adviseAllMethods(advice);
  };

This is a method that is placed in a module class. Note the terminology: advise is the verb ("to advise a method") and advice is the noun ("with this advice"). The MethodAdviceReceiver is a wrapper around the service being advised: you can add advice to some or all methods of the service, and also obtain the interface of the service. It is automatically passed into service advisor methods.

See Injection in Detail Service Advisors for what can be injected into a service advisor method.

...

Service advisor methods are always void methods (this is different from service decorator methods).

The @Match("*") annotation indicates that this advice applies to all services (both your own, and those defined by Tapestry). You will want to narrow down which services are actually targeted in most cases.

...

Advice is pretty efficient, but it is still better to apply it only to methods that make sense. We can improve the service advisor method in our example to only advise methods that return String:

  @Match("*")
  public static void adviseNonNull(MethodAdviceReceiver receiver)
  {
    MethodAdvice advice = new MethodAdvice()
    {
      void advise(Invocation invocation)
      {
        invocation.proceed();

        if (invocation.getResult().equals(null))
          invocation.overrideResult("");
      }
    };

    for (Method m : receiver.getServiceInterface().getMethods())
    {
      if (m.getReturnType().equals(String.class))
        receiver.adviseMethod(m, advice);
    }
  };

Built-in Advice

Tapestry includes two built-in advisor services.

...

Logging advice is built into Tapestry. You can apply logging advice to your services very easily:

  @Match("*")
  public static void adviseLogging(LoggingAdvisor loggingAdvisor, Logger logger, MethodAdviceReceiver receiver)
  {
    loggingAdvisor.addLoggingAdvice(logger, receiver);
  }

LoggingAdvisor is a built-in Tapestry IoC service. This demonstrates how services can be injected into service advisor methods. The Logger parameter is the logger for the service being advised.

...

  @Advise
  @Match("*DAO")
  public static void byServiceId(MethodAdviceReceiver receiver)
  {
    ...
  }

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

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

  @Advise
  @Blue
  public static void byMarkerAnnotation(MethodAdviceReceiver receiver)
  {
    ...
  }

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

By default, @Advise annotation applies the advice 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.

  @Advise(serviceInterface=MyService.class)
  @Match("*DAO")
  public static void byMatchAnnotation(MethodAdviceReceiver receiver)
  {
    ...
  }

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

  @Advise(serviceInterface=MyService.class)
  @Blue
  public static void byMarkerAnnotation(MethodAdviceReceiver receiver)
  {
    ...
  }

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

Decorators and Advice

Service decorators are another way to achieve the same thing; service advisors are a more recent addition, added in Tapestry 5.1.

It is not recommended that you mix advice and decoration. If you do, decoration take precedence; all decorators will be in effect before any advice (internally, they are two separate steps, with advice being processed and the result of that used by the decorators).