Simple tag handlers present a much simpler invocation protocol than do classic tag handlers. The tag library descriptor maps tag library declarations to their physical underlying implementations. A simple tag handler is represented in Java by a class that implements the SimpleTag interface.

The life cycle of a simple tag handler is straightforward and is not complicated by caching semantics. Once a simple tag handler is instantiated by the container, it is executed and then discarded. The same instance must not be cached and reused. Initial performance metrics show that caching a tag handler instance does not necessarily lead to greater performance. To accommodate such caching makes writing portable tag handlers difficult and makes the tag handler prone to error.

In addition to being simpler to work with, simple tag extensions do not rely directly on any servlet APIs, which allows for potential future integration with other technologies. This capability is facilitated by the JspContext class, which Page-Context extends. JspContext provides generic services such as storing the JspWriter and keeping track of scoped attributes, whereas PageContext has functionality specific to serving JSPs in the context of servlets. Whereas the Tag interface relies on PageContext, SimpleTag only relies on JspContext. The body of SimpleTag, if present, is translated into a JSP fragment and passed to the setJspBody method. The tag can then execute the fragment as many times as needed.

See JSP Fragments.

Unlike classic tag handlers, the SimpleTag interface does not extend Tag. Instead of supporting doStartTag() and doEndTag(), the SimpleTag interface provides a simple doTag() method, which is called once and only once for any given tag invocation. All tag logic, iteration, body evaluations, and so on are performed in this single method. Thus, simple tag handlers have the equivalent power of BodyTag, but with a much simpler life cycle and interface.

To support body content, the setJspBody() method is provided. The container invokes the setJspBody() method with a JspFragment object encapsulating the body of the tag. The tag handler implementation can call invoke() on that fragment to evaluate the body. The SimpleTagSupport convenience class provides getJsp-Body() and other useful methods to make this even easier.

• Events in the Simple Tag Handler Life Cycle
  
• JSP Fragments
  

The methods inherited from the Tag or BodyTag interfaces and implemented by the tag handler class are invoked by the JSP engine at specific points during the processing of the JSP page. These methods signify points in the life cycle of a tag and are executed in the following sequence:

1. When the JSP engine encounters a tag in a JSP page, a new tag handler is initialized. The setPageContext() and setParent() methods of the javax.servlet.jsp.tagext.Tag interface are invoked to set up the environment context for the tag handler. As a tag developer, you need not implement these methods if you extend the TagSupport or BodyTagSupport base classes.

2. The setXXXX() JavaBean-like methods for each tag attribute are invoked.

3. The doStartTag() method is invoked. You can define this method in your tag handler class to initialize your tag handler or open connections to any resources it needs, such as a database.

   At the end of the doStartTag() method, you can determine whether the tag body should be evaluated by returning one of the following value constants from your tag handler class:

   SKIP_BODY—Directs the JSP engine to skip the body of the tag. Return this value if the tag is an empty-body tag. The body-related parts of the tag's life cycle are skipped, and the next method invoked is doEndTag().

   EVAL_BODY_INCLUDE—Directs the JSP engine to evaluate and include the content of the tag body. The body-related parts of the tag's life cycle are skipped, and the next method invoked is doEndTag().

   You can only return this value for tags that implement the Tag interface. This allows you to write a tag that can determine whether its body is included, but is not concerned with the contents of the body. You cannot return this value if your tag implements the BodyTag interface (or extends the BodyTagSuport class).

   EVAL_BODY_TAG—Instructs the JSP engine to evaluate the tag body, then invokes the doInitBody() method. You can only return this value if your tag implements the BodyTag interface (or extends the BodyTagSupport class).

4. The setBodyContent() method is invoked. At this point, any output from the tag is diverted into a special JspWriter called BodyContent, and is not sent to the client. All content from evaluating the body is appended to the BodyContent buffer. This method allows the tag handler to store a reference to the BodyContent buffer so it is available to the doAfterBody() method for post-evaluation processing.

   If the tag is passing output to the JSP page (or the surrounding tag scope if it is nested), the tag must explicitly write its output to the parent-scoped JspWriter between this point in the tag life cycle and the end of the doEndTag() method. The tag handler can gain access to the enclosing output using the getEnclosingWriter() method.

   You do not need to implement this method if you are using the BodyTagSupport convenience class, because the tag keeps a reference to the BodyContent and makes the reference available through the getBodyContent() method.

5. The doInitBody() method is invoked. This method allows you to perform some work immediately before the tag body is evaluated for the first time. You might use this opportunity to set up some scripting variables, or to push some content into the BodyContent before the tag body. The content you prepend is not being evaluated as JSP—unlike the tag body content from the JSP page.

   The significant difference between performing work in this method and performing work at the end of the doStartTag() method (once you know you are going to return EVAL_BODY_TAG) is that with this method, the scope of the tag's output is nested and does not go directly to the JSP page (or parent tag). All output is now buffered in a special type of JspWriter called BodyContent.

6. The doAfterBody() method is invoked. This method is called after the body of the tag is evaluated and appended to the BodyContent buffer. Your tag handler should implement this method to perform some work based on the evaluated tag body. If your handler extends the convenience class BodyTagSupport, you can use the getBodyContent() method to access the evaluated body. If you are simply implementing the BodyTag interface, you should have defined the setBodyContent() method where you stored a reference to the BodyContent instance.

   At the end of the doAfterBody() method, you can determine the life cycle of the tag again by returning one of the following value constants:

   SKIP_BODY—Directs the JSP engine to continue, not evaluating the body again. The life cycle of the tag skips to the doEndTag() method.

   EVAL_BODY_TAG—Directs the JSP engine to evaluate the body again. The evaluated body is appended to the BodyContent and the doAfterBody() method is invoked again.

   At this point, you may want your tag handler to write output to the surrounding scope. Obtain a writer to the enclosing scope using the BodyTagSupport.getPreviousOut() method or the BodyContent.getEnclosingWriter() method. Either method obtains the same enclosing writer.

   Your tag handler can write the contents of the evaluated body to the surrounding scope, or can further process the evaluated body and write some other output. Because the BodyContent is appended to the existing BodyContent upon each iteration through the body, you should only write out the entire iterated body content once you decide you are going to return SKIP_BODY. Otherwise, you will see the content of each subsequent iteration repeated in the output.

7. The out writer in the pageContext is restored to the parent JspWriter. This object is actually a stack that is manipulated by the JSP engine on the pageContext using the pushBody() and popBody() methods. Do not, however, attempt to manipulate the stack using these methods in your tag handler.

8. The doEndTag() method is invoked. Your tag handler can implement this method to perform post-tag, server side work, write output to the parent scope JspWriter, or close resources such as database connections.

   Your tag handler writes output directly to the surrounding scope using the JspWriter obtained from pageContext.getOut() in the doEndTag() method. The previous step restored pageContext.out to the enclosing writer when popBody() was invoked on the pageContext.

   You can control the flow for evaluation of the rest of the JSP page by returning one of the following values from the doEngTag() method:

   EVAL_PAGE—Directs the JSP engine to continue processing the rest of the JSP page.

   SKIP_PAGE—Directs the JSP engine to skip the rest of the JSP page.

9. The release() method is invoked. This occurs just before the tag handler instance is de-referenced and made available for garbage collection.

A tag that implements the javax.servlet.jsp.tagext.IterationTag interface has a method available called doAfterBody() that allows you to conditionally re-evaluate the body of the tag. If doAFterBody() returns IterationTag.EVAL_BODY_AGAIN the body is re-evaluated, if doAFterBody() returns Tag.SKIP_BODY, the body is skipped and the doEndTag() method is called. See the Jakarta EE Javadocs for this interface.

You can download the Javadocs at http://www.oracle.com/technetwork/java/javaee/jsp/index.html.

You can catch exceptions thrown from within a tag by implementing the doCatch() and doFinally() methods of the javax.servlet.jsp.tagext.TryCatchFinally interface. See the Jakarta EE Javadocs for this interface.

You can download the Javadocs at http://www.oracle.com/technetwork/java/javaee/jsp/index.html.

• Dynamically Named Scripting Variables
  
• Defining Variables in the Tag Library Descriptor
  

1. Write the validator class.

   A validator class extends the javax.servlet.jsp.tagext.TagLibraryValidator class.

2. Reference the validator in the tag library descriptor.

   For example:

   <validator>
     <validator-class>
        myapp.tools.MyValidator
     </validator-class>
   </validator>

3. (Optional) Define initialization parameters.

   Your validator class can get and use initialization parameters.

   For example:

   <validator>
     <validator-class>
        myapp.tools.MyValidator
     </validator-class>
     <init-param>
       <param-name>myInitParam</param-name>
       <param-value>foo</param-value>
     </init-param>
   </validator>

4. Package the validator class in the WEB-INF/classes directory of a Web application.

   You can also package the classes in a tag library jar file.

   See Packaging a JSP Tag Library as JAR File.