On Sat, 5 Feb 2000, Eduardo Pelegri-Llopart wrote:
> When you say "docs", do you mean the JSP 1.1 spec?
Yes.
> If so, there is such an example in the JSP 1.1 spec (Appendix A,
> Examples, page 135).
It is well hidden there and doesn't do much to make up for the lack of
clarity in the other parts of the spec.
> Any suggestions on how to improve documentation?
Yes, as a matter of fact. :-)
First, I think there is a lot of confusion in the spec about two words:
"body" and "evaluation". I think many people think of these in terms of
the 'text of the body of a tag' and 'something similar to eval() in
Javascript', respecively, when they usually really mean 'the output of the
execution of the body of a tag' and 'execution', respectively.
For example, eduard/o says:
> Say you have
> <x:loop on="object">
> FOO
> <x:insertLoopDependentValue/>
> BAR
> </x:loop>
>
> With semantcs that x:loop will generate a stream that is a sequence of
> its body, reevaluated every time with a new LoopDependentValue. I.e.,
> it is of the form
>
> ... FOO -1st time value- BAR..FOO -2nd time value- BAR..FOO -last time-
> BAR ...
Here I would use 'reexecuted' or just 'executed'.
> Your LoopHandler.doAfterBody method cannot reevaluate its Body. It can
> perform any action it wants, including iterating over structures, etc,
> but the only way it could reevaluate the body is if it had access to the
> body >pre-evaluation<, and if it had access to an "eval()" function, and
> if it had access to the appropriate closure on the evaluation context.
Wait...you just said the body got 'reevaluated every time'! You switched
the meaning of 'evaluate' mid-message from 'execute' to 'eval()'.
I think this ambiguity is the source of much confusion on the part of
those who are trying to wrap their brain around body tags.
>From the spec:
> 5.1.2 -- Overview
>
> BodyTag provides two additional methods for when the tag handler wants
> to manipulate its body.
The tag handler can manipulate the output produced by the body, not the
body itself.
> 5.1.2 -- Actions with Body
>
> The control of the evaluation is actually done based on the result of
> method invocations as follows. The doStartTag() method is always invoked
> first and returns an int value that indicates if the body of the action
> should be evaluated or not. If so (EVAL_BODY_TAG return), a nested
> stream of type BodyContent is created and it is passed to the BodyTag
> object through setBodyContent. Then doInitBody is invoked. Next the body
> is evaluated, with the result going into the newly created BodyContent
> object. Finally the doAfterBody() method of the tag handler object is
> invoked.
>
> If the invocation to doStartTag() returned SKIP_BODY, the body is not
> evaluated at all.
>
> The doBody() methods may use the BodyContent object as it sees fit. For
> example, it may convert it into a String and use it as an argument. Or
> it may do some filter action to it before passing it through to the out
> stream. Or something else.
>
> A doAfterBody() invocation returns an indication of whether further
> reevaluations of the body text should be done by the JSP page; as in the
> case of doStartTag(), if EVAL_BODY_TAG is returned, the body is
> reevaluated, while a return value of SKIP_BODY will stop reevaluations.
> Note that, since server-side objects (accessible via pageContext, or
> through nested handlers) may have changed, each evaluation may produce
> very different content to be added to the BodyContent object.
Again, I would replace 'evaluate' with 'execute'. For doInitBody(), I
would replace EVAL_BODY_TAG with EXEC_BODY. For doAfterBody(), I would
replace EVAL_BODY_TAG with EXEC_BODY_AGAIN and SKIP_BODY with
EXEC_BODY_DONE.
I would add something explicit here about the fact that doAfterBody()
allows for looping of the body execution when it returns EXEC_BODY_AGAIN
(using my terminology) and that doAfterBody() is called after each
iteration until it returns EXEC_BODY_DONE (using my terminology).
> 5.4.4 -- Body Protocol: BodyTag Interface
>
> doAfterBody()
>
> Invoked after every body evaluation. Not invoked in empty tags or in
> tags returning SKIP_BODY in doStartTag. If doAfterBody returns
> EVAL_BODY_TAG, a new evaluation of the body will happen (followed by
> another invocation of doAfterBody). If doAfterBody returns SKIP_BODY no
> more body evaluations will occur, the value of out will be restored
> using the popBody method in pageContext, and then doEndTag will be
> invoked. The method re-invocations may be lead to different actions
> because there might have been some changes to shared state, or because
> of external computation..
This is basically as confusing as the overview and I would change it in
much the same way.
> 5.4.7 -- Life-Cycle Considerations
>
> An Execution Trace
This section should have saved me, but I thought somehow the body was
split into parts rather that being the same body execution each time.
My second comment has to do with packaged tag libraries:
> 5.2.1 -- Packaged Tag Libraries
>
> When packaged sot he JAR file must have a tag library descriptor file
> named META-INF/ taglib.tld.
>
> 5.3.1 -- Locating a Tag Library Descriptor
>
> The URI describing a Tag Library is mapped to a Tag Library Descriptor
> file though two mechanisms: a map in web.xml described using the taglib
> element, and a default mapping.
If a packaged tag library is dropped in WEB-INF/lib as a JAR file, what
does one specify in the taglib directive as the URI to the tld?
Finally, there's some bad english in various places:
> 5.1 -- Goals
>
> Although the JSP specification currently only defines the semantics for
> scripting based on the Java programming language, we want to leave open
> other scripting languages.
...leave open the possibility of other...
> 5.1.2 -- Actions Defining Scripting Variables
>
> The TagExtraInfo class provides methods that will indicate what are the
> names and types of the scripting variables that will be assigned objects
> (at request time) by the action.
...what the names and types of the scripting variables are that...
> 5.2.1 -- Packaged Tag Libraries
>
> When packaged sot he JAR file must have a tag library descriptor file
> named META-INF/ taglib.tld.
When packaged like this, the JAR...
> 5.4.1 -- Properties
>
> At specific moments (after processing the start tag; after processing
> the end tag), the JSP container can automatically synchronize the
> PageContext information with variables in the scripting language so they
> can be made available directly through the scripting elements.
At specific times...
> 5.4.4 -- Body Protocol: BodyTag Interface
>
> When setBodyContent is invoked, the value of the implicit object out has
> already been changed in the pageContext object. The body passed will
> have not data on it.
The passed BodyContent will be empty.
John K Peterson -- IT Services Systems Engineering -- Brigham Young University
[EMAIL PROTECTED]
===========================================================================
To unsubscribe: mailto [EMAIL PROTECTED] with body: "signoff JSP-INTEREST".
FAQs on JSP can be found at:
http://java.sun.com/products/jsp/faq.html
http://www.esperanto.org.nz/jsp/jspfaq.html
