Writing a Tag Handler - Java

You use the interfaces and classes in the javax.servlet.jsp.tagext package to write tag handlers. Figure 1-5 shows the main members of this package.

A tag handler must implement the Tag, IterationTag, or BodyTag interface, or extend a class that implements one of these interfaces. We will look at each of these interfaces, as well as the classes in the javax.servlet.jsp.tagext package.

The Tag Interface

The Tag interface has the following methods: doStartTag, doEndTag, getParent, setParent, setPageContext, and release. The JSP container interacts with the Tag interface as follows:

1. The JSP container instantiates the tag handler or obtains an instance from a pool and calls its setPageContext method, passing a PageContext object representing the JSP page where the custom tag is found.
   
   
2. The JSP container calls the setParent method, passing a tag object that represents the closest tag enclosing the current tag handler. If there is no enclosing tag, a null object reference is passed.
   
   
3. The JSP container sets all the attributes in the custom tag, if any. Attributes are handled like properties in a JavaBean, by using the getter and setter methods. For example, if the custom tag has an attribute named rate, the getter method is called getRate and the setter method is called setRate. The JSP container calls all the available setter methods to set attribute values.
   
   
   

   
   
   Figure 5 The main members of the
   javax.servlet.jsp.tagext package
   

4. The JSP container calls the doStartTag. The doStartTag method can return either Tag.SKIP_BODY or Tag.EVAL_BODY_INCLUDE. If it returns Tag.SKIP_BODY, the JSP container will not process the tag’s body contents, if any. If it returns Tag.EVAL_BODY_INCLUDE, the body contents, if any, will be processed.
   
   
5. Regardless of the return value of the doStartTag method, the JSP container next calls the doEndTag method. This method returns either Tag.SKIP_PAGE or Tag.EVAL_PAGE. If it returns Tag.SKIP_PAGE, the JSP container will not process the remainder of the JSP page. If it returns Tag.EVAL_PAGE, the JSP container processes the rest of the JSP page as normal.
   
   
6. The JSP container calls the release method. You can write cleanup code in this method’s implementation.
   
   
7. The JSP container returns the instance of the tag handler to a pool for future use.

The IterationTag Interface  The IterationTag interface extends the Tag interface and has an extra method called doAfterBody and a static final integer EVAL_BODY_AGAIN. The JSP container invokes the doAfterBody method implementation of a tag handler, implementing IterationTag after it calls the doStartTag method. The doAfterBody method returns either Tag.SKIP_BODY or IterationTag.EVAL_BODY_AGAIN. If the latter is returned, the doAfterBody method is called again. If the return value is Tag.SKIP_BODY, the body will be skipped and the JSP container will call the doEndTag method.

The BodyTag Interface  Implementing the Tag or IterationTag interface does not give you access to the body content of a custom tag. If you want to manipulate the body content, you must implement the BodyTag interface. The BodyTag interface extends IterationTag and adds two methods, doInitBody and setBodyContent, as well as two static final integers, EVAL_BODY_BUFFERED and EVAL_BODY_TAG. The JSP container calls the setBodyContent method after the doStartTag. The doInitBody method is called after the doStartTag method is called.

The doStartTag method of a tag handler implementing the BodyTag interface can return SKIP_BODY, EVAL_BODY_INCLUDE, or EVAL_BODY_BUFFERED. If the method returns EVAL_BODY_INCLUDE, the body is evaluated as it is in IterationTag. If the method returns EVAL_BODY_BUFFERED, a BodyContent object is created that represents the custom tag’s body content.

The doInitBody method can be used to prepare for evaluation of the body. Normally, this method is called by the JSP container after the setBodyContent method. This method will not be called, however, if the custom tag does not have a body content or the doStartTag method returns SKIP_BODY or EVAL_BODY_INCLUDE.

The BodyContext Class  The BodyContent class is an abstract class that extends the javax.servlet.jsp.JspWriter class. The BodyContent class represents the body content of the custom tag, if any. You obtain the body content from the setBodyContent method in the BodyTag interface.

The TagSupport and BodyTagSupportClasses  The javax.servlet.jsp.tagext package also provides support classes that you can extend to create a tag handler. The benefit of extending these classes instead of implementing an interface is that you need to provide only the method implementation of the methods you want to override. As a result, you have shorter code. The TagSupport class implements the IterationTag interface, and the BodyTagSupport implements the BodyTag interface.