Programming Tutorials

The BodyTag Interface in JSP

By: Ivan Lim in JSP Tutorials on 2007-10-06  

The classic tags can evaluate their body content zero, or one or more, times. This is particularly useful when the content to be evaluated is trivial or, in other words, when no transformation or manipulation of the content is required before it's output to the page. If such transformation is required prior to the content being written to the page, you must turn to the BodyTag interface.

The BodyTag Interface

The BodyTag interface further extends the IterationTag interface to add even more flexibility and capability.

BodyTag.java

package javax.servlet.jsp.tagext;
import javax.servlet.jsp.JspException;
public interface BodyTag extends IterationTag {
public final static int EVAL_BODY_BUFFERED = 2;
void setBodyContent(BodyContent b);
void doInitBody() throws JspException;
}

Once again, this interface adds another new constant and two methods that are related to the body content of the tag in question. As you might expect, this means a slightly different life cycle for body tags.

The Body Tag Life Cycle

Figure below summarizes the tag life cycle.

The life cycle of a tag handler that implements the BodyTag interface

Setting the Context

As with all of the other classic tags, first the contextual information (the PageContext and parent Tag) is passed to the tag handler instance.

The Start Tag

After the context has been set, the doStartTag() method is called, and with the BodyTag interface there are three different return values. The doStartTag() method can return SKIP_BODY, meaning that the body content is ignored and processing proceeds to the doEndTag() method, or it can return EVAL_BODY_INCLUDE, signaling that the body content should be evaluated and included in the page. The difference is that the doStartTag() method can now return the EVAL_BODY_BUFFERED constant defined in the BodyTag interface. Returning this value indicates to the JSP container that you want to use the features provided by the BodyTag interface-specifically, that the tag handler will manipulate the body content.

Setting the Body Content

Assuming that you return EVAL_BODY_BUFFERED from the doStartTag() method to indicate that you want to manipulate the body content, the setBodyContent() method is called on the tag handler so that the tag can hold on to the BodyContent reference and use it later. Simple tags have a similar method called setJspBody() that passes a JspFragment instance representing the actual body of the tag. With the BodyTag interface, this process is slightly different. Instead of being passed a JspFragment representing the body content that can subsequently be invoked, the tag handler is passed an object of type BodyContent.

Generating content was simply a matter of finding the JspWriter instance associated with the page and outputting the content. The BodyContent class is a subclass of JspWriter and can be thought of as a temporary scratch-pad area to which content can be written. Behind the scenes, when the JSP container calls the setBodyContent() method, the regular output stream (the JspWriter) is swapped out for a BodyContent object-the same one that gets passed to the tag. This means that any content output from this point onward (until the end tag is reached) is actually written into this temporary scratch pad and not to the page.

The JSP container then calls the doInitBody() method, which can be used to set up any state before the body content is eventually evaluated. The effect of replacing the original JspWriter is that when evaluated, any content between the start and end tags is also written into the BodyContent object, providing you with a way to access the generated content and manipulate it later.

After the Body

As with the IterationTag interface, the doAfterBody() method is called after the body content has been evaluated. There are no changes here; the method should return EVAL_BODY_AGAIN or SKIP_BODY to signal whether more evaluations of the body content are required.

The End Tag

Finally, regardless of whether or not the body was evaluated and reevaluated multiple times, the doEndTag() method is called. Again, possible return values are EVAL_PAGE and SKIP_PAGE. At this point in the life cycle, all of the body content has been evaluated and output into the BodyContent object (the temporary scratch pad). With this in mind, you can now take this content and manipulate/transform it. When you're done, you can then write the final result to the original JspWriter instance.