public abstract class UIComponentClassicTagBase extends UIComponentTagBase implements javax.servlet.jsp.tagext.JspIdConsumer, javax.servlet.jsp.tagext.BodyTag
UIComponentTagBase
is the base class
for all JSP tags that use the "classic" JSP tag interface that
correspond to a UIComponent
instance in
the view. In Faces 1.2, all component tags are BodyTag
instances to allow for the execution of the page to build the
component tree, but not render it. Rendering happens only after the
component tree is completely built.
UIComponentTag
extends
UIComponentClassicTagBase
to add support for properties
that conform to the Faces 1.1 EL.
UIComponentELTag
extends
UIComponentClassicTagBase
class to add support for
properties that conform to the EL API.
The default implementation allows the proper interweaving of template text, non-Faces JSP tag output, and Faces component tag output in the same page, as expected by the page author.
The CASE markers in the following example will be cited in the method descriptions of this class.
CASE 1 describes template text and/or non-component custom tag output occurring as the child of a component tag, but before the first component tag child of that component tag.
CASE 2 describes template text and/or non-component custom tag output occurring between two sibling component tags.
CASE 3 describes template text and/or non-component custom tag output occurring as the child content of an <f:verbatim> tag at any point in the page.
CASE 4 describes template text and/or non-component custom tag output occurring between the last child component tag and its enclosing parent component tag's end tag.
<h:panelGrid style="color:red" border="4" columns="2">
CASE 1
<h:outputText value="component 1"/>
CASE 2
<h:outputText value="component 2"/>
<f:verbatim>CASE 3</f:verbatim>
<c:out value="${pageScope.CASE4}" />
</h:panelGrid>
The preceding arrangement of faces component tags, must yield
markup that will render identically to the following (assuming that
${pageScope.CASE4}
evaluates to "CASE 4
"
without the quotes).
<table border="4" style="color:red">
<tbody>
<tr><td>CASE 1</td></tr> <tr><td>component 1</td></tr>
<tr><td>CASE 2</td> <tr><td>component 2</td></tr>
<tr><td>CASE 3</td> <td>CASE 4</td></tr>
</tbody>
</table>
Constructor and Description |
---|
UIComponentClassicTagBase() |
Modifier and Type | Method and Description |
---|---|
int |
doAfterBody()
Perform any processing necessary to handle the content
implications of CASE 4 in the class description.
|
int |
doEndTag()
Perform any processing necessary to handle the content
implications of CASE 3 in the class description.
|
void |
doInitBody()
Prepare for evaluation of the body.
|
int |
doStartTag()
Perform any processing necessary to find (or create) the
UIComponent instance in the view corresponding to this
tag instance in the page and, if and only if a component was
created, insert it into the tree at the proper location as
expected by the page author. |
javax.servlet.jsp.tagext.BodyContent |
getBodyContent() |
UIComponent |
getComponentInstance()
Return the
UIComponent instance that is associated with
this tag instance. |
boolean |
getCreated()
Return
true if we dynamically created a new component
instance during execution of this tag. |
String |
getJspId() |
javax.servlet.jsp.tagext.Tag |
getParent()
Return the
Tag that is the parent of this instance. |
static UIComponentClassicTagBase |
getParentUIComponentClassicTagBase(javax.servlet.jsp.PageContext context)
Locate and return the nearest enclosing
UIComponentClassicTagBase
if any; otherwise, return null . |
javax.servlet.jsp.JspWriter |
getPreviousOut()
Get the
JspWriter from our BodyContent . |
void |
release()
Release any resources allocated during the execution of this
tag handler.
|
void |
setBodyContent(javax.servlet.jsp.tagext.BodyContent bodyContent)
Set the
bodyContent for this tag handler. |
void |
setId(String id)
Set the component identifier for our component.
|
void |
setJspId(String id)
Defined on
JspIdConsumer . |
void |
setPageContext(javax.servlet.jsp.PageContext pageContext)
Set the
PageContext of the page containing this
tag instance. |
void |
setParent(javax.servlet.jsp.tagext.Tag parent)
Set the
Tag that is the parent of this instance. |
getComponentType, getRendererType
public void setPageContext(javax.servlet.jsp.PageContext pageContext)
Set the PageContext
of the page containing this
tag instance.
setPageContext
in interface javax.servlet.jsp.tagext.Tag
pageContext
- The enclosing PageContext
public javax.servlet.jsp.tagext.Tag getParent()
Return the Tag
that is the parent of this instance.
getParent
in interface javax.servlet.jsp.tagext.Tag
public void setParent(javax.servlet.jsp.tagext.Tag parent)
Set the Tag
that is the parent of this instance.
setParent
in interface javax.servlet.jsp.tagext.Tag
parent
- The new parent Tag
public static UIComponentClassicTagBase getParentUIComponentClassicTagBase(javax.servlet.jsp.PageContext context)
Locate and return the nearest enclosing UIComponentClassicTagBase
if any; otherwise, return null
.
context
- PageContext
for the current pagepublic int doStartTag() throws javax.servlet.jsp.JspException
Perform any processing necessary to find (or create) the
UIComponent
instance in the view corresponding to this
tag instance in the page and, if and only if a component was
created, insert it into the tree at the proper location as
expected by the page author. Secondarily, cause a transient
UIOutput
component to be created and placed in the tree
before the UIComponent
instance for
this tag. The value of this UIOutput
component must include anything covered by CASE 1
or
CASE 2
in the class description.
The default implementation, which is intended to be sufficient
for most components, implements this secondary requirement by
calling getParentUIComponentClassicTagBase(javax.servlet.jsp.PageContext)
, and calling
createVerbatimComponentFromBodyContent()
on the result.
It then adds the returned component to the tree before the
actual component for this tag instance instance by calling
addVerbatimBeforeComponent(javax.faces.webapp.UIComponentClassicTagBase, javax.faces.component.UIComponent, javax.faces.component.UIComponent)
.
Before returning, the component is pushed onto the component
stack for this response to enable the getParentUIComponentClassicTagBase(javax.servlet.jsp.PageContext)
method to work properly.
The flag value to be returned is acquired by calling the
getDoStartValue()
method, which tag subclasses may
override if they do not want the default value.
doStartTag
in interface javax.servlet.jsp.tagext.Tag
javax.servlet.jsp.JspException
- if an error occurspublic int doEndTag() throws javax.servlet.jsp.JspException
Perform any processing necessary to handle the content implications of CASE 3 in the class description.
The default implementation, which is intended to be sufficient
for most components, calls createVerbatimComponentFromBodyContent()
on this instance
and adds it as a child of the component for this tag's component
at the end of the child list. In addition, the following
housekeeping steps are taken.
UIComponent
the set of component
ids of child components created by UIComponentTag
instances the last time this page was processed (if any).
Compare it to the list of children created during this page
processing pass, and remove all children present in the old list
but not the new. Save the new list as a component attribute so
that it gets saved as part of the component's state.UIComponent
the set of facet names
of facets created by UIComponentTag
instances the last
time this page was processed (if any). Compare it to the list of
facets created during this page processing pass, and remove all
facets present in the old list but not the new. Save the new
list as a component attribute so that it gets saved as part of
the component's state.The flag value to be returned is acquired by calling the
getDoEndValue()
method, which tag subclasses may
override if they do not want the default value.
doEndTag
in interface javax.servlet.jsp.tagext.Tag
javax.servlet.jsp.JspException
- if an error occurspublic void release()
Release any resources allocated during the execution of this tag handler.
release
in interface javax.servlet.jsp.tagext.Tag
public void setBodyContent(javax.servlet.jsp.tagext.BodyContent bodyContent)
Set the bodyContent
for this tag handler. This method
is invoked by the JSP page implementation object at most once per
action invocation, before doInitiBody()
. This method
will not be invoked for empty tags or for non-empty tags whose
doStartTag()
method returns SKIP_BODY
or
EVAL_BODY_INCLUDE
.
setBodyContent
in interface javax.servlet.jsp.tagext.BodyTag
bodyContent
- The new BodyContent
for this tagpublic javax.servlet.jsp.JspWriter getPreviousOut()
Get the JspWriter
from our BodyContent
.
public javax.servlet.jsp.tagext.BodyContent getBodyContent()
public void doInitBody() throws javax.servlet.jsp.JspException
Prepare for evaluation of the body. This method is invoked by the
JSP page implementation object after setBodyContent()
and before the first time the body is to be evaluated. This method
will not be invoked for empty tags or for non-empty tags whose
doStartTag()
method returns SKIP_BODY
or EVAL_BODY_INCLUDE
.
doInitBody
in interface javax.servlet.jsp.tagext.BodyTag
javax.servlet.jsp.JspException
- if an error is encounteredpublic int doAfterBody() throws javax.servlet.jsp.JspException
Perform any processing necessary to handle the content implications of CASE 4 in the class description.
Return result from getDoAfterBodyValue()
doAfterBody
in interface javax.servlet.jsp.tagext.IterationTag
javax.servlet.jsp.JspException
- if an error is encounteredpublic void setId(String id)
Set the component identifier for our component. If the
argument begins with UIViewRoot.UNIQUE_ID_PREFIX
throw an
IllegalArgumentException
setId
in class UIComponentTagBase
id
- The new component identifier. This may not start with
UIViewRoot.UNIQUE_ID_PREFIX
.IllegalArgumentException
- if the argument is
non-null
and starts with UIViewRoot.UNIQUE_ID_PREFIX
.public void setJspId(String id)
Defined on JspIdConsumer
. This method is called by
the container before doStartTag()
. The argument is
guaranteed to be unique within the page.
IMPLEMENTATION NOTE: This method will detect where we are in an include and assign a unique ID for each include in a particular 'logical page'. This allows us to avoid possible duplicate ID situations for included pages that have components without explicit IDs.
setJspId
in interface javax.servlet.jsp.tagext.JspIdConsumer
id
- the container generated id for this tag, guaranteed to
be unique within the page.public String getJspId()
public UIComponent getComponentInstance()
Return the UIComponent
instance that is associated with
this tag instance. This method is designed to be used by tags nested
within this tag, and only returns useful results between the
execution of doStartTag()
and doEndTag()
on this tag instance.
getComponentInstance
in class UIComponentTagBase
public boolean getCreated()
Return true
if we dynamically created a new component
instance during execution of this tag. This method is designed to be
used by tags nested within this tag, and only returns useful results
between the execution of doStartTag()
and
doEndTag()
on this tag instance.
getCreated
in class UIComponentTagBase