jsp tag

本文基于Apache Tomcat v5.0。

1 Tag handler
1．1 重用

   Tag handler被保存在org.apache.jasper.runtime.TagHandlerPool对象池中，以下是TagHandlerPool的几个方法： 

    * public TagHandlerPool() 用缺省容量构造TagHandlerPool
    * public Tag get(Class handlerClass) throws JspException 从对象池中取出下个可用的tag handler。如果对象池为空，则实例化一个tag handler（需要注意的是，这个新实例化的tag handler并不被对象池管理）。如果tag handler无法被实例化，那么抛出JspException异常。
    * public void reuse(Tag handler) 把tag handler放回到对象池中等待重用。如果对象池已经达到了容量上限，那么调用tag handler上的release方法。
    * public void release() 在对象池中所有可用的tag handler上调用release方法。

   除了TagHandlerPool之外，还有一个org.apache.jasper.runtime.PerThreadTagHandlerPool对象池。它继承自TagHandlerPool。顾名思义，它是一个基于Thread local的对象池。

   需要注意的是，与继承自TagSupport 和BodyTagSupport 的tag handler不同，实现SimpleTag接口 的tag handler不再被JSP容器缓存。



1．2 TagSupport
    在取得了tag handler之后，JSP容器首先会调用tag hander上的setPageContext(PageContext pc)方法，因此在tag handler的构造函数中不能访问pageContext。之后调用setParent（Tag t）方法和其它属性的注入。
    当遇到标签的起始标记，就会调用public int doStartTag() throws JspException方法。这个方法有Tag.SKIP_BODY和Tag.EVAL_BODY_INCLUDE两个可选的返回值。缺省返回Tag.SKIP_BODY。返回Tag.SKIP_BODY意味着标签之间的内容被忽略；返回Tag.EVAL_BODY_INCLUDE意味着标签之间的内容将被执行。
    如果doStartTag()方法返回值不是Tag.SKIP_BODY，而且在Tag Library Descriptor（tld）文件中该tag的bodycontent属性不是empty，那么在标签之间的内容执行完毕后，就会调用public int doAfterBody() throws JspException方法，这个方法有Tag.SKIP_BODY和IterationTag.EVAL_BODY_AGAIN两个可选的返回值。缺省返回Tag.SKIP_BODY。返回IterationTag.EVAL_BODY_AGAIN意味着标签之间的内容将被执行，然后会再次调用doAfterBody()方法；返回Tag.SKIP_BODY意味着标签之间的内容不再被执行。
    当遇到标签的结束标志，就会调用public int doEndTag() throws JspException方法。这个方法有Tag.EVAL_PAGE和Tag.SKIP_PAGE两个可选的返回值。缺省返回Tag.EVAL_PAGE。返回Tag.EVAL_PAGE意味着按照正常的流程继续执行JSP网页；返回Tag.SKIP_PAGE意味着JSP网页上未处理的部分均被忽略。


1．3 BodyTagSupport
    BodyTagSupport继承了TagSupport，并且实现了BodyTag接口。以下是在BodyTag中声明的两个方法：
Java代码

   1. void setBodyContent(BodyContent b); 
   2. void doInitBody() throws JspException; 

void setBodyContent(BodyContent b);
void doInitBody() throws JspException;

   BodyTagSupport可以用于访问标签体。与TagSupport的doStartTag()方法不同的是，BodyTagSupport的 doStartTag()方法多了一个可选的返回值BodyTag.EVAL_BODY_BUFFERED。如果doStartTag()方法返回值是 BodyTag.EVAL_BODY_BUFFERED，而且在Tag Library Descriptor（tld）文件中该tag的 bodycontent属性不是empty，那么JSP容器会首先调用setBodyContent()和doInitBody()方法。然后在标签之间的内容执行完毕后，会接着调用public int doAfterBody() throws JspException方法。需要注意的是，JSP容器在调用setBodyContent()方法之前，首先会调用pageContext. pushBody()方法，在doAfterBody()方法返回了Tag.SKIP_BODY之后，JSP容器会调用pageContext.popBody()方法。以下是类中这几个方法的代码：
Java代码

   1. public BodyContent pushBody() { 
   2.     return (BodyContent) pushBody(null); 
   3. } 
   4.  
   5. public JspWriter pushBody(Writer writer) { 
   6.     depth++; 
   7.     if (depth >= outs.length) { 
   8.         BodyContentImpl[] newOuts = new BodyContentImpl[depth + 1]; 
   9.         for (int i=0; i<outs.length; i++) { 
  10.             newOuts[i] = outs[i]; 
  11.         } 
  12.         newOuts[depth] = new BodyContentImpl(out); 
  13.         outs = newOuts; 
  14.     } 
  15.  
  16.     outs[depth].setWriter(writer); 
  17.     out = outs[depth]; 
  18.  
  19.     // Update the value of the "out" attribute in the page scope 
  20.     // attribute namespace of this PageContext 
  21.     setAttribute(OUT, out); 
  22.  
  23.     return outs[depth]; 
  24. } 
  25.  
  26. public JspWriter popBody() { 
  27.     depth--; 
  28.     if (depth >= 0) { 
  29.         out = outs[depth]; 
  30.     } else { 
  31.         out = baseOut; 
  32.     } 
  33.  
  34.     // Update the value of the "out" attribute in the page scope 
  35.     // attribute namespace of this PageContext 
  36.     setAttribute(OUT, out); 
  37.  
  38.     return out; 
  39. } 

public BodyContent pushBody() {
    return (BodyContent) pushBody(null);
}

public JspWriter pushBody(Writer writer) {
    depth++;
    if (depth >= outs.length) {
        BodyContentImpl[] newOuts = new BodyContentImpl[depth + 1];
        for (int i=0; i<outs.length; i++) {
            newOuts[i] = outs[i];
        }
        newOuts[depth] = new BodyContentImpl(out);
        outs = newOuts;
    }

    outs[depth].setWriter(writer);
    out = outs[depth];

    // Update the value of the "out" attribute in the page scope
    // attribute namespace of this PageContext
    setAttribute(OUT, out);

    return outs[depth];
}

public JspWriter popBody() {
    depth--;
    if (depth >= 0) {
        out = outs[depth];
    } else {
        out = baseOut;
    }

    // Update the value of the "out" attribute in the page scope
    // attribute namespace of this PageContext
    setAttribute(OUT, out);

    return out;
}

    从以上代码可以知道，在调用了pageContext.pushBody()方法之后，out上的输出被重定向到BodyContent上了（BodyContent这个抽象类继承了JspWriter ），也就是说标签体的执行结果也被输出到BodyContent上了，这就是在doAfterBody()方法内可以通过 getBodyContent().getString()的到标签体输出的原因。



1．4 Simple Tag
    为了简化Tag的开发，从JSP2.0起引入了SimpleTag接口和SimpleTagSupport类。SimpleTag直接继承了JspTag，其定义如下：
Java代码

   1. public void doTag() throws  JspException, IOException; 
   2. public void setParent( JspTag parent ); 
   3. public JspTag getParent(); 
   4. public void setJspContext( JspContext pc ); 
   5. public void setJspBody( JspFragment jspBody ); 

public void doTag() throws  JspException, IOException;
public void setParent( JspTag parent );
public JspTag getParent();
public void setJspContext( JspContext pc );
public void setJspBody( JspFragment jspBody );

   为了访问标签体，SimpleTag中包含了setJspBody( JspFragment jspBody )方法，JSP容器会把标签体封装到JspFragment 后进行注入。在doTag()方法内，可以任意多次的调用getJspBody().invoke(Writer w)方法来执行标签体。在tld文件中，SimpleTag对应的body-content不可以设置成JSP。

   JSP2.0同时新增了DynamicAttributes接口为标签增加动态属性的功能。JSP容器会在调用doTag()方法前，调用其接口上的如下方法进行属性的注入：
Java代码

   1. void setDynamicAttribute(String uri, String localName, Object value) throws JspException 

void setDynamicAttribute(String uri, String localName, Object value) throws JspException



1．5 Tag File
    Tag File也是JSP2.0新增的主要功能之一，它允许开发人员使用JSP语法来制作标签。Tag File的扩展名为.tag或.tagx。假如Tag File 包含其他完整或片断的Tag File，建议扩展名为.tagf。Tag File通常被放置在WEB-INF/tags/目录下。Tag File的隐含对象（Implicit Object）有request，response，jspContext，session，application，out，config。Tag File中可以使用<jsp:doBody>和<jsp:invoke>这两个action元素。<jsp:doBody>可以用来执行标签体。<jsp:invoke>可以用来执行标签中JspFragment类型的属性。
    Tag File转译后的Java类继承自SimpleTagSupport，需要注意的是，在这个类的setJspContext( JspContext pc )方法中，传入的参数JspContext被org.apache.jasper.runtime.JspContextWrapper进行了包装。被包装的JspContext 上的跟Nested Variable同名的属性也会被保存到JspContextWrapper上。JspContextWrapper的setAttribute()方法会拦截对PAGE_SCOPE属性的设置：这些属性并不保存在被包装的JspContext上，而是保存在JspContextWrapper上。在执行标签内容之前，JSP容器会把JspContextWrapper上Nested 和 AT_BEGIN Variables拷贝到被包装的JspContext 的PAGE_SCOPE中。在执行完标签体之后，JSP容器会复原之前保存在JspContextWrapper上的Nested Variable到被包装的JspContext 上，同时拷贝AT_END Variables到被包装的JspContext 上。