loading table of contents...

4.3.2.1. Lookup

By annotating a bean's method with the @Link annotation, this method is turned into a link scheme. Typically, an application consists of several link schemes for different aspects as every handler is likely to have one or more link schemes as a counterpart. When a link generation is requested, by running, for example,

<cm:link target="${bean}" view="rss">
  <cm:param name="maxItems" value="10"/>
</cm:link>

from within a JSP template, the CAE needs to find a link scheme that matches best. This decision is made based on the information that is provided by the link generation invocation: The given target bean, the view name, any additional link parameters.

The parameters of the @Link annotation are used to determine methods that are link handler candidates. The parameters are turned into predicates which are evaluated against the arguments passed to the link generation request. In the following example, the annotated method is a candidate for beans of type ContentBean with views "rss" or "xml" and link parameter "maxItems":

@Link(type=ContentBean.class,
      view={"rss","xml"},
      parameter="maxItems",
      order=10)

The predicates are evaluated in the following order to determine the ordering of the link handler candidates.

  • type: The java class(es), that the given bean needs to match (either by class equality or by class super type relationship). Several types might be listed here but only a single type needs to match. If no type is specified, then the bean method parameter determines the type. Hence a link handler method with a parameter of type ContentBean would match every instance of ContentBean if no subclass of ContentBean is given as type parameter. A link handler method with the same parameters but a more specific type parameter in its @Link annotation would have a higher precedence, though.

  • view: A list of supported view names. If this predicate is specified, the given view name needs to match one of the listed names. Omitting this predicates matches all view names. A view name "DEFAULT" matches the default ("null") view.

  • parameter: A list of link parameters that need to be specified. In contrast to other predicates, all parameter predicates need to match here.

  • order: A numeric order value to distinguish the precedence in case if more than one scheme matches all the criteria given above. A higher order value correlates here with a lower precedence. The default value is set to Integer.MAX_VALUE.

There might be situations where more than one link scheme matches the current link generation invocation. In this case, all matching schemes are invoked until one scheme returns a non-null result. The more specific a link scheme is, the earlier it is invoked.