Defining Tag Extra Info Objects

Every custom tag can have an optional Tag Extra Info (TEI) object. The TEI object is used for two purposes:

• To validate tag attributes at page translation time

• To specify the scripting variables created by the tag

A TEI class extends the javax.servlet.jsp.tagext.TagExtraInfo class and is defined to the TLD before the tag's body content definition. The following example defines an OptionTagTEI class for the OptionTag used in the case study:

<tag>
    <name>option</name>
    <tag-class>web.OptionTag</tag-class>
    <tei-class>web.OptionTagTEI</tei-class>
    <body-content>empty</body-content>

The TEI class itself must define methods to validate attributes and define scripting variables. These uses of the TEI class are presented in the next two sub-sections.

Validating Attributes

As you know from Day 13, when a JSP is first accessed, the JSP is translated into a Java servlet that is then compiled. After the compiled servlet is available, it is used to process the client's HTTP request. The process of translating the JSP text and compiling the servlet can fail (and frequently does during page development). As explained on Day 13, some of the most common errors are as follows:

• JSP syntax errors

• Compilation errors in embedded Java scriptlets

• Incorrectly specifying tag attributes

The first of these errors can be reduced by using JSP, HTML, and XML syntax-aware editors.

The second problem is reduced when custom tags are used to encapsulate Java code, enabling Java compilation errors to be detected and corrected as the tag is developed.

Solving the third problem of misusing attributes for a custom tag is addressed by defining a Tag Extra Info class to validate your attributes. You would do this if you had specific rules about which attributes could be defined or the value an attribute could have.

As an example, you can update the Option tag from the previous section to allow a second attribute, called default, which could be used when a single option is required rather than force the developer to construct an array of strings. The selected and default attributes for your tag would be mutually exclusive. The TLD entry defining the <variable> tag cannot express this constraint, but you can by using a TEI class.

The TEI class defines a single method called isValid(). The single parameter is a javax.servlet.jsp.tagext.TagData that provides a getAttribute() method to access each of the tag's attributes. The example in Listing 14.16 shows how the revised Option tag could validate that the default and selected attributes are not both defined.

Listing 14.16. Full Text of OptionTagTEI.java

 1: package web;
 2:
 3: import javax.servlet.jsp.*;
 4: import javax.servlet.jsp.tagext.*;
 5:
 6: public class OptionTagTEI extends TagExtraInfo {
 7:    public boolean isValid(TagData data) {
 8:       Object selected = data.getAttribute("selected");
 9:       Object def = data.getAttribute("default");
10:       if (def!=null && selected!=null)
11:           return false;
12:       else
13:           return true;
14:    }
15: }
						

The advertise.jsp can be updated to use the default attribute for accessing the location list:

<agency:option default='<%=job.getLocation()%>'/>

The OptionTag.java class needs updating to support the default attribute. This is a simple change that adds the getDefault() and setDefault() bean methods shown next:

public void setDefault (String selected) {
        this.selected = new String[]{selected};
    }

    public String getDefault () {
        return selected[0];
    }

To use the Tag Extra Info to validate the value of a parameter, you will need to verify that the value is not a request time expression. Only if the value is a static Java String can it be compared against the permitted values. The example in Listing 14.17 verifies that a tag's color attribute can only take the values red, yellow, amber and green.

Listing 14.17. TEI Example to Validate a Color Attribute

 1: public class SignalTagTEI extends TagExtraInfo {
 2:    public boolean isValid(Tagdata data) {
 3:       Object o = data.getAttribute("color");
 4:       if (o != null && o != TagData.REQUEST_TIME_VALUE) {
 5:           String color = (String)o;
 6:           if (col.equals("red") || col.equals("yellow") ||
 7:              col.equals("amber") || col.equals("green"))
 8:             return true;
 9:           else
10:             return false;
11:       }
12:       else
13:          return true;
14:    }
15: }
						

Defining Scripting Variables

The second use of the Tag Extra Info class is to provide information about the scripting variables used by the tag. This TEI information is not required for deploying a tag that creates scripting variables, but it does provide information that can be used by some manufacturer's JSP design tools.

The following example shows how the getCust tag shown in Listing 14.7 could define the cust scripting variable:

public class DefineTei extends TagExtraInfo {
   public VariableInfo[] getVariableInfo(TagData data) {
      String type = data.getAttributeString("type");
      if (type == null)
         type = "java.lang.Object";
      return new VariableInfo[] {
               new VariableInfo(data.getAttributeString("id"),
              type, true, VariableInfo.AT_BEGIN)};
   }
}

The name (cust) and class (agency.Advertise) of the scripting variable are passed in as tag attributes. The TagData.getAttributeString() method can retrieve this information and use it to construct the VariableInfo object required as a return value from this method. The scope of the variable is set to be VariableInfo.AT_BEGIN to allow it to be used after the opening tag.