package-summary.html

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

container (via generated code).  The setter methods used to set
the properties are discovered using the JavaBeans introspector
machinery.

<p> The protocol supported by a tag handler provides for passing of
parameters, the evaluation and reevaluation of the body of the action,
and for getting access to objects and other tag handlers in the
JSP page.

<p> A tag handler instance is responsible for processing one request
at a time.  It is the responsability of the JSP container to enforce
this.

<p> Additional translation time information associated with the action
indicates the name of any scripting variables it may introduce, their
types and their scope. At specific moments, the JSP container will
automatically synchronize the <A HREF="../../../../javax/servlet/jsp/PageContext.html" title="class in javax.servlet.jsp"><CODE>PageContext</CODE></A>
 information with variables
in the scripting language so they can be made available directly
through the scripting elements.


<h3>Properties</h3>


<p> A tag handler has some properties.  All tag handlers have a
<em>pageContext</em> property for the JSP page where the tag is
located, and a <em>parent</em> property for the tag handler to the
closest enclosing action. Specific tag handler classes may have
additional properties.

<p> All attributes of a custom action must be JavaBeans component
properties, although some properties may not be exposed as attributes.
The attributes that are visible to the JSP translator are exactly
those listed in the Tag Library Descriptor (TLD).

<p> All properties of a tag handler instance exposed as attributes
will be initialized by the container using the appropriate setter
methods before the instance can be used to perform the action methods.
It is the responsibility of the JSP container to invoke the
appropriate setter methods to initialize these properties.  It is the
responsability of user code, be it scriptlets, JavaBeans code, or code
inside custom tags, to not invoke these setter methods, as doing
otherwise would interfere with the container knowledge.

<p> The setter methods that should be used when assigning a value to
an attribute of a custom action are determined by using the JavaBeans
introspector on the tag handler class, then use the setter method
associated with the property that has the same name as the attribute
in question. An implication (unclear in the JavaBeans specification)
is that there is only one setter per property.

<p> Unspecified attributes/properties should not be set (using a
setter method).

<p> Once properly set, all properties are expected to be persistent,
so that if the JSP container ascertains that a property has already
been set on a given tag handler instance, it must not set it
again.  

<p> The JSP container may reuse classic tag handler instances for multiple
occurrences of the corresponding custom action, in the same page or in
different pages, but only if the same set of attributes are used for all
occurrences.  If a tag handler is used for more than one occurence, the
container must reset all attributes where the values differ between the
custom action occurrences.  Attributes with the same value in all
occurrences must not be reset.  If an attribute value is set as a
request-time attribute value (using a scripting or an EL expression),
the container must reset the attribute between all reuses of the tag
handler instance. 

<p> User code can access property information and access and modify
tag handler internal state starting with the first action method (doStartTag)
up until the last action method (doEndTag or doFinally for tag handlers
implementing TryCatchFinally).


<h3>Tag Handler as a Container-Managed Object</h3>

<p> Since a tag handler is a container managed object, the container
needs to maintain its references; specifically, user code should not
keep references to a tag handler except between the start of the first
action method (doStartTag()) and the end of the last action method
(doEndTag() or doFinally() for those tags that implement TryCatchFinally).

<p> The restrictions on references to tag handler objects and
on modifying attribute properties gives the JSP container substantial
freedom in effectively managing tag handler objects to achieve different
goals.  For example, a container may implementing different pooling strategies
to minimize creation cost, or may hoist setting of properties to reduce
cost when a tag handler is inside another iterative tag. 


<h3>Conversions</h3>

<p>A tag handler implements an action; the JSP container must follow
the type conversions described in Section 2.13.2 when assigning values
to the attributes of an action.

<h3>Empty and Non-Empty Actions</h3>

An empty action has no body; it may use one of two syntaxes: either
&lt;foo/&gt; or &lt;foo&gt;&lt;/foo&gt;.  Since empty actions have no
body the methods related to body manipulation are not invoked.
There is a mechanism in the Tag Library Descriptor to indicate
that a tag can only be used to write empty actions; when used,
non-empty actions using that tag will produce a translation error.

<p>
A non-empty action has a body.  

<a name="tag interface">
<h3>The Tag Interface</h3>
</a>   

<p> A Tag handler that does not want to process its body can implement
just the Tag interface.  A tag handler may not want to process its
body because it is an empty tag or because the body is just to
be "passed through".

<p> The Tag interface includes methods to provide page context
information to the Tag Handler instance, methods to handle the
life-cycle of tag handlers, and two main methods for performing
actions on a tag: <code>doStartTag()</code> and
<code>doEndTag()</code>.  The method <code>doStartTag()</code> is
invoked when encountering the start tag and its return value indicates
whether the body (if there is any) should be skipped, or evaluated and
passed through to the current response stream.  The method
<code>doEndTag()</code> is invoked when encountering the end tag; its
return value indicates whether the rest of the page should continue to
be evaluated or not.

<p> If an exception is encountered during the evaluation of the
body of a tag, its doEndTag method will not be evaluated.  See the
TryCatchFinally tag for methods that are guaranteed to be evaluated.

<a name="iterationtag interface">
<h3>The IterationTag Interface</h3>
</a>   

<p> The IterationTag interface is used to repeatedly reevaluate
the body of a custom action.  The interface has one method:
<code>doAfterBody()</code> which is invoked after each evaluation
of the body to determine whether to reevaluate or not.

<p> Reevaluation is requested with the value 2, which in JSP 1.1 is
defined to be BodyTag.EVAL_BODY_TAG.  That constant value is still
kept in JSP 1.2 (for full backwards compatibility) but, to improve
clarity, a new name is also available: IterationTag.EVAL_BODY_AGAIN.
To stop iterating, the returned value should be 0, which is
Tag.SKIP_BODY.

<h3>The JspIdConsumer Interface</h3>
This interface indicates to the container that a tag handler wishes 
to be provided with a compiler generated ID that is unique
within the page.

<h3>The TagSupport Base Class</h3>

<p> The TagSupport class is a base class that can be used when
implementing the Tag or IterationTag interfaces.


<a name="bodycontent">
<h2>2. Tag Handlers that want Access to their Body Content</h2>
</a>

<p>The evaluation of a body is delivered into a <code>BodyContent</code>
object.  This is then made available to tag handlers that implement
the <code>BodyTag</code> interface.  The <code>BodyTagSupport</code>
class provides a useful base class to simplify writing these handlers.


<p> If a Tag handler wants to have access to the content of its body
then it must implement the <code>BodyTag</code> interface.

This interface extends IterationTag, provides two additional methods
<code>setBodyContent(BodyContent)</code> and
<code>doInitBody()</code>
and refers to an object of type BodyContent.

<p> A BodyContent is a subclass of <code>JspWriter</code> that has a
few additional methods to convert its contents into a String, insert
the contents into another JspWriter, to get a Reader into its
contents, and to clear the contents.  Its semantics also assure that
buffer size will never be exceeded.

<p> The JSP page implementation will create a BodyContent if the
doStartTag() method returns a EVAL_BODY_BUFFERED.  This object will be
passed to doInitBody(); then the body of the tag will be evaluated,
and <em>during that evaluation <b>out</b> will be bound to the
BodyContent just passed to the BodyTag handler</em>.  Then
doAfterBody() will be evaluated.  If that method returns SKIP_BODY, no
more evaluations of the body will be done; if the method returns
EVAL_BODY_AGAIN, then the body will be evaluated, and doAfterBody() will
be invoked again.

<p> The content of a BodyContent instance remains available until after
the invocation of its associated doEndTag() method.

<p> A common use of the BodyContent is to extract its contents into a
String and then use the String as a value for some operation.  Another
common use is to take its contents and push it into the out Stream
that was valid when the start tag was encountered (that is available
from the PageContext object passed to the handler in setPageContext).


<a name="dynamic">
<h2>3. Dynamic Attributes</h2>
</a>

<p>Any tag handler can optionally extend the <code>DynamicAttributes</code>
interface to indicate that it supports dynamic attributes.  In addition 
to implementing the <code>DynamicAttributes</code> interface, tag 
handlers that support dynamic attributes must declare that they do so in 
the Tag Library Descriptor.</p>

<p>The TLD is what ultimately determines whether a tag handler accepts 
dynamic attributes or not. If a tag handler declares that it supports 
dynamic attributes in the TLD but it does not implement the 
<code>DynamicAttributes</code> interface, the tag handler must be 
considered invalid by the container.</p>

<p>If the dynamic-attributes element for a tag being invoked contains 
the value "true", the following requirements apply:</p>

<ul>
  <li>For each attribute specified in the tag invocation that does not 
  have a corresponding attribute element in the TLD for this tag, 
  a call must be made to <code>setDynamicAttribute()</code>, 
  passing in the namespace of the attribute (or null if the attribute
  does not have a namespace or prefix), the name of the attribute without 
  the namespace prefix, and the final value of the attribute.</li>

  <li>Dynamic attributes must be considered to accept request-time
  expression values as well as deferred expressions.</li>

  <li>Dynamic attributes must be treated as though they were of type
  <code>java.lang.Object</code>. If a <code>ValueExpression</code> 
  is passed as a dynamic attribute, the default value for the expected 
  return type is assumed to be <code>java.lang.Object</code>.  If a 
  <code>MethodExpression</code> is passed as a dynamic
  attribute, the default method signature is assumed to be <code>void
  method()</code>.</li>
  
  <li>Note that passing a String literal as a dynamic attribute will never
  be considered as a deferred expression.</li>

  <li>The JSP container must recognize dynamic attributes that are 
  passed to the tag handler using the &lt;jsp:attribute&gt; standard 
  action.</li>

  <li>If the <code>setDynamicAttribute()</code> method throws
  <code>JspException</code>, the <code>doStartTag()</code> or 
  <code>doTag()</code> method is not invoked for this tag, and the
  exception must be treated in the same manner as if it came from 
  a regular attribute setter method.</li>

  <li>For a JSP document in either standard or XML syntax, If a
  dynamic attribute has a prefix that doesn't map to a
  namespace, a translation error must occur.  In standard
  syntax, only namespaces defined using taglib directives are
  recognized.</li>

</ul>

<p>In the following example, assume attributes a and b are declared 
using the attribute element in the TLD, attributes d1 and d2 are not 
declared, and the dynamic-attributes element is set to "true". 
The attributes are set using the calls:
<ul>
  <li><code>setA( "1" )</code>, </li>
  <li><code>setDynamicAttribute( null, "d1", "2" )</code>, </li>
  <li><code>setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d2", "3" )</code>, </li>
  <li><code>setB( "4" )</code>, </li>
  <li><code>setDynamicAttribute( null, "d3", "5" )</code>, and</li>
  <li><code>setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d4", "6" )</code>.</li>
</ul>

<pre>
&lt;jsp:root xmlns:mytag="http://www.foo.com/jsp/taglib/mytag.tld" version="2.0"&gt;
  &lt;mytag:invokeDynamic a="1" d1="2" mytag:d2="3"&gt;
    &lt;jsp:attribute name="b"&gt;4&lt;/jsp:attribute&gt;
    &lt;jsp:attribute name="d3"&gt;5&lt;/jsp:attribute&gt;
    &lt;jsp:attribute name="mytag:d4"&gt;6&lt;/jsp:attribute&gt;
  &lt;/mytag:invokeDynamic&gt;
&lt;/jsp:root&gt;
</pre>

<a name="thmgmt">
<h2>4. Annotated Tag Handler Management Example</h2>
</a>

Below is a somewhat complete example of the way one JSP container
could choose to do some tag handler management.  There are many
other strategies that could be followed, with different pay offs.

<p>In this example, we are assuming that
x:iterate is an iterative tag, while x:doit and x:foobar are simple
tag.  We will also assume that x:iterate and x:foobar implement the
TryCatchFinally interface, while x:doit does not.

<pre>
&lt;x:iterate src="foo"&gt;
  &lt;x:doit att1="one" att2="&lt;%= 1 + 1 %&gt;" /&gt;
  &lt;x:foobar /&gt;
  &lt;x:doit att1="one" att2="&lt;%= 2 + 2 %&gt;" /&gt;
&lt;/x:iterate&gt;
&lt;x:doit att1="one" att2="&lt;%= 3 + 3 %&gt;" /&gt;
</pre>

<p> The particular code shown below assumes there is some pool of tag
handlers that are managed (details not described, although pool
managing is simpler when there are no optional attributes), and
attemps to reuse tag handlers if possible.  The code also "hoists" 
setting of properties to reduce the cost when appropriate, e.g. inside
an iteration.