To associate the contained tags with some particular purpose or context, it is often useful to provide custom tags that act as containers for other types of custom tag. Examples in Listing 1 include the dimensions tag, the sliceDimensions tag, and the includeFilter tag. All three of these tags can contain dimension tags, and in each case, the contained tags specify the dimensions which are to be applied in a particular way when fetching the data. Listing 6 shows the dimensions tag again for reference.

Listing 6. The dimensions tag from Listing 1

<%@ taglib uri="/WEB-INF/tlds/dd.tld" prefix="dd" %>

<dd:data id="sales">
  <dd:dataSource>Sales Figures</dd:dataSource>

  <dd:dimensions>
    <dd:dimension>Year</dd:dimension>
    <dd:dimension>Product</dd:dimension>
  </dd:dimensions>

  and so forth..

The dimension tag will implement the JSP BodyTag interface, as it needs to work with the text contents of the tag (which is the dimension name). The most straightforward implementation is to extend the BodyTagSupport class, and override the doEndTag method to extract the body text. However, it is not the dimension tag itself that needs to know the dimension name. It is actually the containing tag (the dimensions tag in this example) that knows what to do with it. So, a system is needed for passing the dimension name to whatever containing tag can handle it.

The JSP findAncestorWithClass static method is very helpful for locating a suitable containing tag. Notice that this method does not only look at the immediate containing tag (which is known as the parent tag), but continues to look at parent tags all the way out until it either finds one that is suitable or runs out of tags to look at. This is important because the example here has the dimensions tag as an immediate parent of the dimension tags that are within it. Many reasons exist why other tags might come in-between. For example, the page author might use some suitable conditional inclusion tags to selectively activate certain combinations of the contained tags, and the findAncestorWithClass method will step past any such intervening tags and find the required containing tag if it exists.

Of course, quite a variety of tags might want to contain dimension tags. To enable the dimension tag handler to find the right container, a Java interface is created. Listing 7 shows a suitable interface. Any custom tag that is designed to contain dimension tags needs to implement this interface, as well as the JSP Tag interface. Listing 8 shows a typical implementation of the doEndTag method for the dimension tag itself.

Listing 7. An interface for containers of dimension tags to implement

public interface DimensionTagContainer
{
  /**
   * Supply the name of a dimension from a contained dimension tag.
   * @param dimensionName The name of the contained dimension.
   * @throws JspTagException If this tag cannot accept the contained dimension.
   */
  void addDimensionName(String dimensionName)
  throws JspTagException;
}

Listing 8. Implementing the dimension tag handler

public class DimensionTag extends javax.servlet.jsp.tagext.BodyTagSupport
{
 /**
  * Give the body content as a dimension name to the containing tag.
  */
 public int doEndTag()
 throws JspException
 {
  final DimensionTagContainer container =
   (DimensionTagContainer)TagSupport.findAncestorWithClass(this, DimensionTagContainer.class);

  container.addDimensionName(getBodyContent().getString());

  return EVAL_PAGE;
 }
}

You can use this same strategy repeatedly at each level of containment. The data tag needs to contain several types of custom tags, including the dimensions tag we have been discussing. By implementing a suitable interface, the data tag can ensure that it will be found by the dimensions tag handler, which can then report to it the complete set of dimension names to be fetched. The dimensions tag will be told each of these names by the dimension tags it contains, and it will store these in a suitable list until its own doEndTag method is called.