package-summary.html

j2ee帮助文档软件设计/软件工程 文件格式

<pre>

boolean b1, b2;
IterationTag i; // for x:iterate
Tag d; // for x:doit
Tag d; // for x:foobar

page: // label to end of page...


// initialize iteration tag
i = get tag from pool or new();

i.setPageContext(pc);
i.setParent(null);
i.setSrc("foo");

// x:iterate implements TryCatchFinally
try {
    if ((b1 = i.doStartTag()) == EVAL_BODY_INCLUDE) {

        // initialize doit tag
        // code has been moved out of the loop for show
        d = get tag from pool or new();

        d.setPageContext(pc);
        d.setParent(i);
        d.setAtt1("one");

    loop:
        while (1) do {
            // I'm ignoring newlines...

            // two invocations, fused together

            // first invocation of x:doit
            d.setAtt2(1+1);
            if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
                // nothing
            } else if (b2 != SKIP_BODY) {
                // Q? protocol error ...
            }
            if ((b2 = d.doEndTag()) == SKIP_PAGE) {
                break page;  // be done with it.
            } else if (b2 != EVAL_PAGE) {
                // Q? protocol error
            }

            // x:foobar invocation
            f = get tag from pool or new();
            f.setPageContext(pc);
            f.setParent(i);

            // x:foobar implements TryCatchFinally
            try {
        
                if ((b2 = f.doStartTag()) == EVAL_BODY_INCLUDE) {
                    // nothing
                } else if (b2 != SKIP_BODY) {
                    // Q? protocol error
                }
                if ((b2 = f.doEndTag()) == SKIP_PAGE) {
                    break page;  // be done with it.
                } else if (b2 != EVAL_PAGE) {
                    // Q? protocol error
                }
            } catch (Throwable t) {
                f.doCatch(t); // caught, may been rethrown!
            } finally {
                f.doFinally();
            }

            // put f back to pool
        
            // second invocation of x:doit
            d.setAtt2(2+2);
            if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
                // nothing
            } else if (b2 != SKIP_BODY) {
                // Q? protocol error
            }
            if ((b2 = d.doEndTag()) == SKIP_PAGE) {
                break page;  // be done with it.
            } else if (b2 != EVAL_PAGE) {
                // Q? protocol error
            }

            if ((b2 = i.doAfterBody()) == EVAL_BODY_AGAIN) {
                break loop;
            } else if (b2 != SKIP_BODY) {
                // Q? protocol error
            }
        // loop
        }

    } else if (b1 != SKIP_BODY) {
        // Q? protocol error
    }

    // tail end of the IteratorTag ...

    if ((b1 = i.doEndTag()) == SKIP_PAGE) {
        break page;   // be done with it.
    } else if (b1 != EVAL_PAGE) {
        // Q? protocol error
    }
    
    // third invocation
    // this tag handler could be reused from the previous ones.
    d = get tag from pool or new();

    d.setPageContext(pc);
    d.setParent(null);
    d.setAtt1("one");
    d.setAtt2(3+3);

    if ((b1 = d.doStartTag()) == EVAL_BODY_INCLUDE) {
        // nothing
    } else if (b1 != SKIP_BODY) {
        // Q? protocol error
    }
    if ((b1 = d.doEndTag()) == SKIP_PAGE) {
        break page;  // be done with it.
    } else if (b1 != EVAL_PAGE) {
        // Q? protocol error
    }

} catch (Throwable t) {
    i.doCatch(t); // caught, may been rethrown!
} finally {
    i.doFinally();
}
</pre>

<a name="coop">
<h2>5. Cooperating Actions</h2>
</a>

Actions can cooperate with other actions and with scripting code
in a number of ways.

<h3>PageContext</h3>
<p>

Often two actions in a JSP page will want to cooperate,
perhaps by one action creating some server-side object that
needs to be accessed by another.
One mechanism for doing this is by giving the object a name
within the JSP page; the first action will create the object
and associate the name to it while the second action
will use the name to retrieve the object.

<p>
For example, in the following JSP segment the <code>foo</code>
action might create a server-side object and give it the
name "myObject". 
Then the <code>bar</code>
action might access that server-side object and take some action.

<blockquote>
<code>
<pre>
&lt;x:foo id="myObject" /&gt;
&lt;x:bar ref="myObjet" /&gt;
</pre>
</code>
</blockquote>

<p>

In a JSP implementation, the mapping "name"->value is kept by the
implicit object
<code>pageContext</code>.

This object is passed around through the Tag handler instances
so it can be used to communicate information: all it is needed
is to know the name under which the information is stored into
the pageContext.

<h3>The Runtime Stack</h3>
<p>

An alternative to explicit communication of information through
a named object is implicit coordination based on syntactic scoping.

<p>
For example, in the following JSP segment the <code>foo</code>
action might create a server-side object;
later the nested <code>bar</code> action might access that server-side object.
The object is not named within the <code>pageContext</code>:
it is found because the specific <code>foo</code> element is the
closest enclosing instance of a known element type.

<blockquote>
<code>
<pre>
&lt;foo&gt;
   &lt;bar/&gt;
&lt;/foo&gt;
</pre>
</code>
</blockquote>

<p>
This functionality is supported through the
<code>TagSupport.findAncestorWithClass(Tag, Class)</code>,
which uses a reference to parent tag kept by each Tag instance,
which effectively provides a run-time execution stack.

<a name="simple">
<h2>6. Simple Tag Handlers</h2>
</a>

<p> This section presents the API to implement Simple Tag Handlers.  
Simple Tag Handlers present a much simpler invocation 
protocol than do Classic Tag Handlers.</p>

<p>The Tag Library Descriptor maps tag library declarations to their 
physical underlying implementations. A Simple Tag Handler is 
represented in Java by a class which implements the 
<code>SimpleTag</code> interface.</p>

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

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

<h3>Lifecycle of Simple Tag Handlers</h3>
<p>This section describes the lifecycle of simple tag handlers, from 
creation to invocation. For all semantics left unspecified by this 
section, the semantics default to that of a classic tag handler.</p>

<p>When a simple tag handler is invoked, the following steps occur 
(in order):</p>

<ol>
  <li>Simple tag handlers are created initially using a zero 
  argument constructor on the corresponding implementation class. 
  Unlike classic tag handlers, this instance must never be pooled by 
  the container. A new instance must be created for each tag invocation.</li>

  <li>The <code>setJspContext()</code> and <code>setParent()</code> 
  methods are invoked on the tag handler.  The <code>setParent()</code>
  method need not be called if the value being passed in is 
  <code>null</code>.  In the case of tag files, a <code>JspContext</code> 
  wrapper is created so that the tag file can appear to have its own page 
  scope.  Calling <code>getJspContext()</code> must return the wrapped 
  <code>JspContext</code>.</li>

  <li>The attributes specified as XML element attributes (if any) 
  are evaluated next, in the order in which they are declared, according 
  to the following rules (referred to as "evaluating an XML element 
  attribute" below).  The appropriate bean property setter is invoked 
  for each.  If no setter is defined for the specified attribute but 
  the tag accepts dynamic attributes, the <code>setDynamicAttribute()</code> 
  method is invoked as the setter.
    <ul>
      <li>If the attribute is a scripting expression (e.g. "&lt;%= 1+1 %&gt;"
      in JSP syntax, or "%= 1+1 %" in XML syntax), the expression is 
      evaluated, and the result is converted as per the rules in 
      "Type Conversions", and passed to the setter.</li>

      <li>Otherwise, if the attribute contains any Expression Language 
      expressions (e.g. "Hello ${name}"), the expression is evaluated, and 
      the result is converted and passed to the setter.</li>

      <li>Otherwise, the attribute value is taken verbatim, converted, 
      and passed to the setter.</li>
    </ul>
  </li>

  <li>The value for each &lt;jsp:attribute&gt; element is evaluated, 
  and the corresponding bean property setter methods are invoked for 
  each, in the order in which they appear in the body of the tag. If no
  setter is defined for the specified attribute but the tag 
  accepts dynamic attributes, the <code>setDynamicAttribute()</code> 
  method is invoked as the setter.
    <ul>
      <li>Otherwise, if the attribute is not of type 
      <code>JspFragment</code>, the container evaluates the body of 
      the &lt;jsp:attribute&gt; element. This evaluation can be done 
      in a container-specific manner. Container implementors should 
      note that in the process of evaluating this body, other custom 
      actions may be invoked.</li>

      <li>Otherwise, if the attribute is of type <code>JspFragment</code>,
      an instance of a <code>JspFragment</code> object is created and
      passed in.</li>
    </ul>
  </li>

  <li>The value for the body of the tag is determined, and if
  a body exists the <code>setJspBody()</code> method is called on the 
  tag handler. 
    <ul>
      <li>If the tag is declared to have a <code>body-content</code> 
      of "<code>empty</code>" or no body or an empty body is passed 
      for this invocation, then <code>setJspBody()</code> is not 
      called.</li>

      <li>Otherwise, the body of the tag is either the body of 
      the &lt;jsp:body&gt; element, or the body of the custom action 
      invocation if no &lt;jsp:body&gt; or &lt;jsp:attribute&gt; 
      elements are present.  In this case, an instance of a
      <code>JspFragment</code> object is created as per the lifecycle