D.3 Tag Handler Types

[ Team LiB ]

D.3 Tag Handler Types The JSP specification defines a number of classes and interfaces in the javax.servlet.jsp.tagext package. These classes are used to develop tag handler classes for JSP custom actions. This section contains descriptions of each class and interface. Chapter 21 and Chapter 22 show examples of how you can use these classes and interfaces to develop custom actions. BodyContent The container creates an instance of the BodyContent class to encapsulate the element body of a custom action element if the corresponding tag handler implements the BodyTag interface. The container makes the BodyContent instance available to the tag handler by calling the setBodyContent( ) method, so the tag handler can process the body content. Synopsis Class name: javax.servlet.jsp.tagext.BodyContent Extends: javax.servlet.jsp.JspWriter Implements: None Implemented by: Internal container-dependent class Constructor protected BodyContent(JspWriter e) Creates a new instance with the specified JspWriter as the enclosing writer. Methods public void clearBody( ) Removes all buffered content for this instance. public void flush( ) throws java.io.IOException Overwrites the behavior inherited from JspWriter to always throw an IOException, because it's invalid to flush a BodyContent instance. public JspWriter getEnclosingWriter( ) Returns the enclosing JspWriter, i.e., either the top level JspWriter or the JspWriter (BodyContent subclass) of the parent tag handler. public abstract java.io.Reader getReader( ) Returns the value of this BodyContent as a Reader with the content produced by evaluating the element's body. public abstract String getString( ) Returns the value of this BodyContent as a String with the content produced by evaluating the element's body. public abstract void writeOut(java.io.Writer out)throws java.io.IOException Writes the content of this BodyContent into a Writer. BodyTag The BodyTag interface extends the IterationTag interface. It must be implemented by classic tag handler classes that need access to the body contents of the corresponding custom action element, for instance in order to perform a transformation of the contents before it's included in the response. A tag handler that implements this interface must return EVAL_BODY_BUFFERED from doStartTag( ) to tell the container to capture the result of evaluating the body. It can also return EVAL_BODY_AGAIN from doAfterBody( ) to tell the container to evaluate the body again and capture the result. Unless you need to allow scripting elements in the corresponding custom action element body, I recommend that you use the SimpleTag interface instead. Synopsis Interface name: javax.servlet.jsp.tagext.BodyTag Extends: javax.servlet.jsp.tagext.IterationTag Implemented by: Custom action tag handler classes and javax.servlet.jsp.tagext.BodyTagSupport Fields public static final int EVAL_BODY_BUFFERED Methods public void doInitBody( ) throws JspException Prepares for evaluation of the body. This method is invoked once per action invocation by the page implementation after a new BodyContent has been obtained and set on the tag handler via the setBodyContent( ) method and before the evaluation of the element's body. This method isn't invoked if the element body is empty or if doStartTag( ) returns SKIP_BODY. public void setBodyContent(BodyContent b) Sets the BodyContent created for this tag handler. This method isn't invoked if the element body is empty or if doStartTag( ) returns SKIP_BODY. BodyTagSupport BodyTagSupport is a support class that provides default implementations of all BodyTag interface methods. It's intended to be used as a superclass for classic tag handlers that need access to the body contents of the corresponding custom action element. Unless you need to allow scripting elements in the corresponding custom action element body, I recommend that you use the SimpleTagSupport class instead. Synopsis Class name: javax.servlet.jsp.tagext.BodyTagSupport Extends: javax.servlet.jsp.tagext.TagSupport Implements: javax.servlet.jsp.tagext.BodyTag Implemented by: Internal container-dependent class. Most containers use the reference implementation of the class (developed in the Apache Jakarta project) Fields protected javax.servlet.jsp.tagext.BodyContent bodyContent Constructor public BodyTagSupport( ) Creates a new BodyTagSupport instance. Methods public int doAfterBody( ) Returns SKIP_BODY. public int doEndTag( ) Returns EVAL_PAGE. public void doInitBody( ) This method does nothing in the BodyTagSupport class. public int doStartTag( ) Returns EVAL_BODY_BUFFERED. public BodyContent getBodyContent( ) Returns the BodyContent object assigned to this instance. public JspWriter getPreviousOut( ) Returns the enclosing writer of the BodyContent object assigned to this instance. public void release( ) Removes the references to all objects held by this instance. public void setBodyContent(BodyContent b) Saves a reference to the BodyContent in the bodyContent instance variable. DynamicAttributes The DynamicAttributes interface can be implemented by a tag handler in addition to one of the main tag handler interfaces to support attributes not declared in the TLD. Synopsis Interface name: javax.servlet.jsp.tagext.DynamicAttributes Extends: None Implemented by: Custom action tag handler classes Methods public void setDynamicAttribute(String uri, String localName, Object value) throws JspException Called by the container to pass the tag handler an undeclared attribute. The URI is the attribute's XML namespace identifier or null if it's in the default namespace. IterationTag The IterationTag interface extends the Tag interface. Classic tag handler classes that need their corresponding action element body evaluated more than once but that don't need to access the result of the body evaluation must implement this interface. Unless you need to allow scripting elements in the corresponding custom action element body, I recommend that you use the SimpleTag interface instead. Synopsis Interface name: javax.servlet.jsp.tagext.IterationTag Extends: javax.servlet.jsp.tagext.Tag Implemented by: Custom action tag handler classes and javax.servlet.jsp.tagext.TagSupport. Fields public static final int EVAL_BODY_AGAIN Methods public int doAfterBody( ) throws JspException Performs actions after the body has been evaluated. This method is invoked after every body evaluation. If this method returns EVAL_BODY_AGAIN, the body is evaluated again, typically after changing the value of variables used in the body. If it returns SKIP_BODY, the processing continues with a call to doEndTag( ). This method is not invoked if the element body is empty or if doStartTag( ) returns SKIP_BODY. JspContext The JspContext class represents an interface to the generic runtime environment available to a simple tag handler, even in a nonservlet environment. In a servlet-based JSP container, an instance of the PageContext subclass, described in the Implicit Variables section, is always used. Synopsis Class name: javax.servlet.jsp.JspContext Extends: None Implements: None Implemented by: Internal container-dependent class; most containers use the reference implementation of the class (developed in the Apache Jakarta project) Constructor public JspContext( ) Creates a new JspContext instance. Methods public abstract Object findAttribute(String name) Searches for the named attribute in the page, request, session (if valid), and application scope in order and returns the first value it finds or null if the attribute is not found. public abstract Object getAttribute(String name) Returns the object associated with the specified attribute name in the page scope or null if the attribute is not found. public abstract Object getAttribute(String name, int scope) Returns the object associated with the specified attribute name in the specified scope or null if the attribute is not found. The scope argument must be one of the int values specified by the PageContext static scope variables. public abstract java.util.Enumeration getAttributeNamesInScope(int scope) Returns an enumeration of String objects containing all attribute names for the specified scope. The scope argument must be one of the int values specified by the PageContext static scope variables. public abstract int getAttributesScope(String name) Returns one of the int values specified by the PageContext static scope variables for the scope of the object associated with the specified attribute name or 0 if the attribute is not found. public abstract ExpressionEvaluator getExpressionEvaluator( ) Returns an ExpressionEvaluator that can be used for programmatic EL expression evaluation. public abstract JspWriter getOut( ) Returns the current JspWriter for the page. When a tag handler that implements BodyTag (or is nested in the body of another action element) calls this method, the returned object may be an instance of the BodyContent subclass. public abstract VariableEvaluator getVariableEvaluator( ) Returns a VariableEvaluator that can be used with an ExpressionEvaluator for programmatic EL expression evaluation. public JspWriter popBody( ) This method is intended to be called only by the JSP page implementation class. It reassigns the previous JspWriter, saved by the matching pushBody( ) method, as the current JspWriter and returns the same instance. public JspWriter pushBody(java.io.Writer writer) This method is intended to be called only by the JSP page implementation class. It returns a new JspWriter that ultimately writes to the provided Writer and updates the out variable to point to the new instance. A reference to the old JspWriter, if any, is also kept so it can be reassigned when popBody( ) is called. public abstract void removeAttribute(String name) Removes the object reference associated with the specified attribute name in the page scope. public abstract void removeAttribute(String name, int scope) Removes the object reference associated with the specified attribute name in the specified scope. The scope argument must be one of the int values specified by the PageContext static scope variables. public abstract void setAttribute(String name, Object attribute) Saves the specified attribute name and object in the page scope. public abstract void setAttribute(String name, Object o, int scope) Saves the specified attribute name and object in the specified scope. The scope argument must be one of the int values specified by the PageContext static scope variables. JspFragment The JspFragment class represents an object that encapsulates a set of JSP actions and/or EL expressions, possibly mixed with template text, that a tag handler can invoke as many times as needed. The container creates an instance of this class for the body of a custom action implemented by a simple tag handler, as well as for the body of the <jsp:attribute> for an attribute of type JspFragment. Synopsis Class name: javax.servlet.jsp.tagext.JspFragment Extends: None Implements: None Implemented by: Internal container-dependent class; most containers use the reference implementation of the class (developed in the Apache Jakarta project) Methods public abstract JspContext getJspContext( ) Returns the JspContext that is bound to this fragment. public abstract void invoke(java.io.Writer out) throws JspException Executes the fragment and directs all output to the provided Writer or to the JspWriter returned by the getOut( ) method of the JspContext associated with the fragment if no Writer is provided. JspTag The JspTag interface is an empty interface, serving as the common parent interface for the Tag and SimpleTag interfaces to allow nesting of custom actions implemented by both classic and simple tag handlers. SimpleTag The SimpleTag interface defines the new, easier to use, tag handler API introduced in JSP 2.0. Tag handlers implementing this interface are referred to as simple tag handler (tag handlers based on the older API are referred to as classic tag handlers). The container creates a new instance of the class that implements this interface for each invocation. A tag handler implementing this interface can do everything a classic tag handler can do, except that the corresponding custom action element must not contain scripting elements (i.e., the tag handler must be declared to have a body content of empty, scriptless, or tagdependent). Synopsis Interface name: javax.servlet.jsp.tagext.SimpleTag Extends: javax.servlet.jsp.tagext.JspTag Implemented by: Custom action tag handler classes Methods public void doTag( ) throws JspException, SkipPageException, java.io.IOException Performs all processing for the tag handler using the properties and attributes previously set by the setter methods. If the page processing must be terminated after processing of this tag handler (e.g., if the tag handler forwards or redirects to another resource), this method must throw a SkipPageException. public JspTag getParent( ) Returns the parent tag handler or null if there's no parent. public void setJspBody(JspFragment jspBody) Sets the fragment that represents the custom action element's body. The container doesn't call this method if the custom action element body is empty. public void setJspContext(JspContext context) Sets the context for the JSP page. In a JSP environment, this is always an instance of the PageContext subclass. The tag handler can access all JSP scopes, request and response information, and more through the context object. public void setParent(JspTag parent) Sets the parent tag handler. The container doesn't call this method if the tag handler doesn't have a parent. SimpleTagSupport The SimpleTagSupport class provides default implementations of all SimpleTag interface methods, plus a method for finding a parent of a specific type. It's intended to be used as a superclass for simple tag handlers. Synopsis Class name: javax.servlet.jsp.tagext.SimpleTagSupport Extends: None Implements: javax.servlet.jsp.tagext.SimpleTag Implemented by: Internal container-dependent class; most containers use the reference implementation of the class (developed in the Apache Jakarta project) Constructor public SimpleTagSupport( ) Creates a new instance. Methods public void doTag( ) throws JspException, SkipPageException, java.io.IOException Performs all processing for the tag handler using the properties and attributes previously set by the setter methods. If the page processing must be terminated after processing of this tag handler (e.g., if the tag handler forwards or redirects to another resource), this method must throw a SkipPageException. The default implementation in this class doesn't do anything, so this method must be implemented by the subclass. public static final JspTag findAncestorWithClass(JspTag from, Class klass) Locates the closest parent tag handler of the specified class for the specified tag handler. It uses the getParent( ) method of the Tag and SimpleTag interfaces to look for the parent. For every instance of TagAdapter returned by a getParent( ) call, the object returned by TagAdapter getAdaptee( ) is compared to the specified class. If a match is found this way, the getAdaptee( ) value is returned by this method. public JspFragment getJspBody( ) Returns the fragment passed to the setJspBody( ) method or null if there's nobody. public JspContext getJspContext( ) Returns the context passed to the setJspContext( ) method. public JspTag getParent( ) Returns the parent tag handler passed to the setParent( ) method or null if there's no parent. public void setJspBody(JspFragment jspBody) Sets the fragment that represents the custom action element's body. The container doesn't call this method if the custom action element body is empty. public void setJspContext(JspContext context) Sets the context for the JSP page. In a JSP environment, this is always an instance of the PageContext subclass. The tag handler can access all JSP scopes, request and response information, and more through the context object. public void setParent(JspTag parent) Sets the parent tag handler. The container doesn't call this method if the tag handler doesn't have a parent. Tag The Tag interface is the main classic tag handler interface. It should be implemented by classic tag handler classes that do not need the body of the corresponding action element evaluated more than once and that do not need access to the result of the body evaluation. Unless you need to allow scripting elements in the corresponding custom action element body, I recommend that you use the SimpleTag interface instead. Synopsis Interface name: javax.servlet.jsp.tagext.Tag Extends: javax.servlet.jsp.tagext.JspTag Implemented by: Custom action tag handler classes Fields public static final int EVAL_BODY_INCLUDE public static final int EVAL_PAGE public static final int SKIP_BODY public static final int SKIP_PAGE Methods public int doEndTag( ) throws JspException Performs actions when the end tag is encountered. If this method returns SKIP_PAGE, execution of the rest of the page is aborted, and the _jspService( ) method of JSP page implementation class returns. If EVAL_PAGE is returned, the code following the custom action in the _jspService( ) method is executed. public int doStartTag( ) throws JspException Performs actions when the start tag is encountered. This method is called after all property setter methods have been called. The return value from this method controls how the action's body, if any, is handled. If it returns EVAL_BODY_INCLUDE, the JSP container evaluates the body and processed possible JSP elements. The result of the evaluation is added to the response. If SKIP_BODY is returned, the body is ignored. A tag handler class that implements the BodyTag interface (extending the IterationTag interface, which extends the Tag interface) can return EVAL_BODY_BUFFERED instead of EVAL_BODY_INCLUDE. The JSP container then creates a BodyContent instance and makes it available to the tag handler for special processing. public Tag getParent( ) Returns the tag handler's parent (the Tag instance for the enclosing action element, if any) or null if the tag handler doesn't have a parent. public void release( ) Removes the references to all objects held by this instance. public void setPageContext(PageContext pc) Saves a reference to the current PageContext. public void setParent(Tag t) Saves a reference to the tag handler's parent (the Tag instance for the enclosing action element). TagAdapter The TagAdapter class makes it possible to nest classic and simple tag handlers by working around a type mismatch between the old and new tag handler APIs, namely the fact that the setParent( ) method in the Tag interface takes an instance of Tag while the SimpleTag interface doesn't extend Tag. The container creates an instance of TagAdapter to wrap a SimpleTag implementation when a simple tag handler is the parent of a classic tag handler and uses the TagAdapter as the setParent( ) argument. The findAncestorWithClass( ) method in SimpleTagSupport knows how to deal with TagAdapter instances it may find in the parent chain. Synopsis Class name: javax.servlet.jsp.tagext.TagAdapter Extends: None Implements: javax.servlet.jsp.tagext.Tag Implemented by: Internal container-dependent class; most containers use the reference implementation of the class (developed in the Apache Jakarta project) Constructor public TagAdapter(SimpleTag adaptee) Creates a new instance that wraps the given SimpleTag. Methods public int doEndTag( ) throws JspException Never called by the container. Throws UnsupportedOperationException. public int doStartTag( ) throws JspException Never called by the container. Throws UnsupportedOperationException. public JspTag getAdaptee( ) Returns the wrapped tag handler. public Tag getParent( ) Returns the wrapped tag handler's parent tag handler. public void release( ) Never called by the container. Throws UnsupportedOperationException. public void setPageContext( ) Never called by the container. Throws UnsupportedOperationException. public void setParent( ) Never called by the container. Throws UnsupportedOperationException. TagSupport TagSupport is a support class that provides default implementations of all IterationTag interface methods. It's intended to be used as a superclass for classic tag handlers that do not need to evaluate the corresponding action element body or need access to the evaluation result. Unless you need to allow scripting elements in the corresponding custom action element body, I recommend that you use the SimpleTagSupport class instead. Synopsis Class name: javax.servlet.jsp.tagext.TagSupport Extends: None Implements: java.io.Serializable, javax.servlet.jsp.tagext.IterationTag Implemented by: Internal container-dependent class; most containers use the reference implementation of the class (developed in the Apache Jakarta project) Fields protected String id protected PageContext pageContext Constructor public TagSupport( ) Creates a new instance. Methods public int doAfterBody( ) Returns SKIP_BODY. public int doEndTag( ) Returns EVAL_PAGE. public int doStartTag( ) Returns SKIP_BODY. public static final Tag findAncestorWithClass(Tag from, Class klass) Returns the instance of the specified class, found by testing for a match of each parent in a tag handler nesting structure (corresponding to nested action elements) starting with the specified Tag instance or null if not found. public String getId( ) Returns the id attribute value or null if not set. public Tag getParent( ) Returns the parent of this Tag instance (representing the action element that contains the action element corresponding to this Tag instance) or null if the instance has no parent (at the top level in the JSP page). public Object getValue(String k) Returns the value for the specified attribute that has been set with the setValue( ) method or null if not found. public java.util.Enumeration getValues( ) Returns an Enumeration of all attribute names for values set with the setValue( ) method. public void release( ) Removes the references to all objects held by this instance. public void removeValue(String k) Removes a value set with the setValue( ) method. public void setId(String id) Sets the id attribute value. public void setPageContext(PageContext pageContext) Saves a reference to the current PageContext. public void setParent(Tag t) Saves a reference to the parent for this instance. public void setValue(String k, Object o) Saves the specified attribute with the specified value. Subclasses can use this method to save attribute values as an alternative to instance variables. TryCatchFinally The TryCatchFinally interface provides methods for handling exceptions thrown while evaluating the body of an action element and can be implemented by a tag handler in addition to one of the main tag handler interfaces: Tag, IterationTag, and BodyTag. Synopsis Interface name: javax.servlet.jsp.tagext.TryCatchFinally Extends: None Implemented by: Custom action tag handler classes Methods public void doCatch(Throwable exception) throws Throwable Handles the specified exception and may optionally rethrow the same exception or a new exception. This method is invoked by the container if an exception is thrown when evaluating the body or by calling doStartTag( ), doEndTag( ), doInitBody( ), or doAfterBody( ). public void doFinally( ) Typically clears per-invocation state, such as closing expensive resources used only for one invocation. This method is invoked after doEndTag( ) or after doCatch( ) if an exception is thrown when evaluating the body or by calling doStartTag( ), doEndTag( ), doInitBody( ), or doAfterBody( ).

[ Team LiB ]