TagSupport Class | |
Class name: | |
javax.servlet.jsp.tagext.TagSupport |
|
Extends: | |
None |
|
Implements: | |
Tag, java.io.Serializable |
|
Implemented by: | |
Internal container-dependent class. Most containers use the reference implementation of the class (developed in the Apache Jakarta project). |
|
Description | |
TagSupport is a support class that provides default implementations for all Tag interface methods. It's intended to be used as a superclass for tag handlers that do not need access to the body contents of the corresponding custom action elements. |
|
Example | |
An example of a custom action that can be implemented as a simple tag handler (that is, just implementing the Tag interface) is an action that adds a cookie to the HTTP response. Let's call this action <ora:addCookie>. The tag handler class is called com.ora.jsp.tags.generic.AddCookieTag and extends the TagSupport class to inherit most of the Tag interface method implementations: package com.ora.jsp.tags.generic; import javax.servlet.http.*; import javax.servlet.jsp.*; import javax.servlet.jsp.tagext.*; import com.ora.jsp.util.*; public class AddCookieTag extends TagSupport { The <ora:addCookie> action has two mandatory attributes, name and value, and one optional attribute, maxAge. Each attribute is represented by an instance variable and a standard property setter method: private String name; private String value; private String maxAgeString; public void setName(String name) { this.name = name; } public void setValue(String value) { this.value = value; } public void setMaxAge(String maxAgeString) { this.maxAgeString = maxAgeString; } All setter methods set the corresponding instance variables. The purpose of the custom action is to create a new javax.servlet.Cookie object with the name, value, and maxAge values specified by the attributes and add the cookie to the response. The tag handler class overrides the doEndTag() method to carry out this work: public int doEndTag() throws JspException { int maxAge = -1; if (maxAgeString != null) { try { maxAge = Integer.valueOf(maxAgeString). intValue(); } catch (NumberFormatException e) { throw new JspException("Invalid maxAge: " + e.getMessage()); } } sendCookie(name, value, maxAge, (HttpServletResponse) pageContext.getResponse()); return EVAL_PAGE; } private void sendCookie(String name, String value, int maxAge, HttpServletResponse res) { Cookie cookie = new Cookie(name, value); cookie.setMaxAge(maxAge); res.addCookie(cookie); } The maxAge attribute is optional, so before the corresponding String value is converted to an int, a test is performed to see if it's set. Similar tests are not necessary for the name and value variables because the web container verifies that all mandatory attributes are set in the custom action. If a mandatory attribute is not set, the web container refuses to process the page-so you can always be sure that a variable corresponding to a mandatory attribute has a value. Whether an attribute is mandatory is specified in the TLD for the library. The tag handler class should also implement the release() method, to release all references to objects it has acquired: public void release() { name = null; value = null; maxAgeString = null; super.release(); } The release() method is called when the tag handler is no longer needed. The AddCookieTag class sets all its properties to null and calls super.release() to let the TagSupport class do the same. This makes all property objects available for garbage collection. A TagSupport method that's not needed for this example but can be handy in other situations is the findAncestorWithClass() method. It can be used by a tag handler for a nested action element to find its parent. The nested tag handler can then call methods implemented by the parent tag handler class to get from or provide information to the parent. For example, it can provide the <jsp:param> elements nested within the body of <jsp:forward> and <jsp:include> standard JSP action elements. An equivalent custom action for a nested parameter element could be implemented with a tag handler that uses the findAncestorWithClass() method like this: import javax.servlet.jsp.*; import javax.servlet.jsp.tagext.*; public class ParamTag extends TagSupport { private String name; private String value; public void setName(String name) { this.name = name; } public void setValue(String value) { this.value = value; } public int doEndTag() throws JspException { Tag parent = findAncestorWithClass(this, ParamParent.class); if (parent == null) { throw new JspException("The param action is not " + "enclosed by a supported action type"); } ParamParent paramParent = (ParamParent) parent; paramParent.setParam(name, URLEncoder. encode(value)); return EVAL_PAGE; } } |
TagSupport() | |
public TagSupport() | |
Creates a new instance with the specified name and value. |
doEndTag() | |
public int doEndTag() throws JspException | |
Returns EVAL_PAGE. |
doStartTag() | |
public int doStartTag() throws JspException | |
Returns SKIP_BODY. |
findAncestorWithClass() | |
public static final Tag findAncestorWithClass(Tag from, Class class) | |
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. |
getId() | |
public String getId() | |
Returns the id attribute value, or null if not set. |
getParent() | |
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 (i.e., is at the top level in the JSP page). |
getValue() | |
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. |
getValues() | |
public java.util.Enumeration getValues() | |
Returns an Enumeration of all attribute names for values set with the setValue() method. |
release() | |
public void release() | |
Removes the references to all objects held by this instance. |
removeValue() | |
public void removeValue(String k) | |
Removes a value set with the setValue() method. |
setPageContext() | |
public void setPageContext(PageContext pageContext) | |
Saves a reference to the current PageContext. |
setId() | |
public void setId(String id) | |
Sets the id attribute value. |
setParent() | |
public void setParent(Tag t) | |
Saves a reference to the parent for this instance. |
setValue() | |
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. |