Class UIComponentClassicTagBase
- All Implemented Interfaces:
BodyTag
,IterationTag
,JspIdConsumer
,JspTag
,Tag
- Direct Known Subclasses:
UIComponentELTag
,UIComponentTag
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>
-
Field Summary
Modifier and TypeFieldDescriptionprotected BodyContent
ThebodyContent
for this tag handler.protected PageContext
The JSPPageContext
for the page we are embedded in.protected static final String
Used as the prefix for ids.Fields inherited from class javax.faces.webapp.UIComponentTagBase
log
Fields inherited from interface javax.servlet.jsp.tagext.BodyTag
EVAL_BODY_BUFFERED, EVAL_BODY_TAG
Fields inherited from interface javax.servlet.jsp.tagext.IterationTag
EVAL_BODY_AGAIN
Fields inherited from interface javax.servlet.jsp.tagext.Tag
EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionprotected void
addChild
(UIComponent child) Add the component identifier of the specifiedUIComponent
to the list of component identifiers created or located by nestedUIComponentTag
s processing this request.protected void
Add the facet name of the specified facet to the list of facet names created or located by nestedUIComponentTag
s processing this request.protected void
addVerbatimAfterComponent
(UIComponentClassicTagBase parentTag, UIComponent verbatim, UIComponent component) Add verbatim as a sibling of component in component in the parent's child list.protected void
addVerbatimBeforeComponent
(UIComponentClassicTagBase parentTag, UIComponent verbatim, UIComponent component) Add verbatim as a sibling of component in component in the parent's child list.protected abstract UIComponent
createComponent
(FacesContext context, String newId) Create and return a new child component of the type returned by callinggetComponentType()
.protected UIOutput
Use theApplication
instance to create a new component with the following characteristics.protected UIComponent
Create a transient UIOutput component from the body content, of this tag instance or return null if there is no body content, the body content is whitespace, or the body content is a comment.int
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
Prepare for evaluation of the body.int
Perform any processing necessary to find (or create) theUIComponent
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.protected void
Deprecated.No encoding is done during JSP page execution.protected void
Deprecated.No encoding is done during JSP page execution.protected void
Deprecated.No encoding is done during JSP page execution.protected UIComponent
findComponent
(FacesContext context) Find and return theUIComponent
, from the component tree, that corresponds to this tag handler instance.Return theUIComponent
instance that is associated with this tag instance.boolean
Returntrue
if we dynamically created a new component instance during execution of this tag.Returns theList
ofUIComponent
ids created or located by nestedUIComponentTag
s while processing the current request.protected int
Return the flag value that should be returned from thedoAfterBody()
method when it is called.protected int
Return the flag value that should be returned from thedoEnd()
method when it is called.protected int
Return the flag value that should be returned from thedoStart()
method when it is called.protected FacesContext
Return theFacesContext
instance for the current request.protected String
If this method has been called before on this tag's useful lifetime (beforerelease()
was called), return the previously returned value.protected String
Return the facet name that we should be stored under, if any; otherwise, return null (indicating that we will be a child component).protected String
getId()
Return theid
value assigned by the page author.protected int
Return the index of the next child to be added as a child of this tag.getJspId()
Return theTag
that is the parent of this instance.static UIComponentClassicTagBase
Locate and return the nearest enclosingUIComponentClassicTagBase
if any; otherwise, returnnull
.Get theJspWriter
from ourBodyContent
.protected abstract boolean
Returntrue
if this component has a non-null
binding attribute.void
release()
Release any resources allocated during the execution of this tag handler.void
setBodyContent
(BodyContent bodyContent) Set thebodyContent
for this tag handler.void
Set the component identifier for our component.void
Defined onJspIdConsumer
.void
setPageContext
(PageContext pageContext) Set thePageContext
of the page containing this tag instance.void
Set theTag
that is the parent of this instance.protected abstract void
setProperties
(UIComponent component) Override properties and attributes of the specified component, if the corresponding properties of this tag handler instance were explicitly set.protected void
Set up theResponseWriter
for the current response, if this has not been done already.Methods inherited from class javax.faces.webapp.UIComponentTagBase
getComponentType, getELContext, getRendererType
-
Field Details
-
UNIQUE_ID_PREFIX
Used as the prefix for ids. This is necessary to avoid uniqueness conflicts with the transient verbatim components.- See Also:
-
bodyContent
The
bodyContent
for this tag handler. -
pageContext
The JSP
PageContext
for the page we are embedded in.
-
-
Constructor Details
-
UIComponentClassicTagBase
public UIComponentClassicTagBase()
-
-
Method Details
-
getDoStartValue
Return the flag value that should be returned from the
doStart()
method when it is called. Subclasses may override this method to return the appropriate value.- Throws:
JspException
- to causedoStart()
to throw an exception
-
getDoEndValue
Return the flag value that should be returned from the
doEnd()
method when it is called. Subclasses may override this method to return the appropriate value.- Throws:
JspException
- to causedoEnd()
to throw an exception
-
encodeBegin
Deprecated.No encoding is done during JSP page execution. Encoding is deferred until the page has completed executing to allow the entire tree to be built before any encoding occurs.Delegate to the
encodeBegin()
method of our correspondingUIComponent
. This method is called fromdoStartTag()
. Normally, delegation occurs unconditionally; however, this method is abstracted out so that advanced tags can conditionally perform this call.- Throws:
IOException
- if an input/output error occurs
-
encodeChildren
Deprecated.No encoding is done during JSP page execution. Encoding is deferred until the page has completed executing to allow the entire tree to be built before any encoding occurs.Delegate to the
encodeChildren()
method of our correspondingUIComponent
. This method is called fromdoStartTag()
. Normally, delegation occurs unconditionally; however, this method is abstracted out so that advanced tags can conditionally perform this call.- Throws:
IOException
- if an input/output error occurs
-
encodeEnd
Deprecated.No encoding is done during JSP page execution. Encoding is deferred until the page has completed executing to allow the entire tree to be built before any encoding occurs.Delegate to the
encodeEnd()
method of our correspondingUIComponent
. This method is called fromdoStartTag()
. Normally, delegation occurs unconditionally; however, this method is abstracted out so that advanced tags can conditionally perform this call.- Throws:
IOException
- if an input/output error occurs
-
setPageContext
Set the
PageContext
of the page containing this tag instance.- Specified by:
setPageContext
in interfaceTag
- Parameters:
pageContext
- The enclosingPageContext
-
getParent
Return the
Tag
that is the parent of this instance. -
setParent
Set the
Tag
that is the parent of this instance. -
setupResponseWriter
protected void setupResponseWriter()Set up the
ResponseWriter
for the current response, if this has not been done already.@deprecated.
ViewHandler.renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot)
is now responsible for setting up the response writer. This method is now a no-op. -
findComponent
Find and return the
UIComponent
, from the component tree, that corresponds to this tag handler instance. If there is no suchUIComponent
, create one and add it as a child or facet of theUIComponent
associated with our nearest enclosingUIComponentTag
. The process for locating or creating the component is:- If we have previously located this component, return it.
- Locate the parent component by looking for a parent
UIComponentTag
instance, and ask it for its component. If there is no parentUIComponentTag
instance, this tag represents the root component, so get it from the currentTree
and return it. - If this
UIComponentTag
instance has thefacetName
attribute set, ask the parentUIComponent
for a facet with this name. If not found, create one, callsetProperties()
with the new component as a parameter, and register it under this name. Return the found or created facetUIComponent
. - Determine the component id to be assigned to the new
component, as follows: if this
UIComponentTag
has anid
attribute set, use that value; otherwise, generate an identifier that is guaranteed to be the same for thisUIComponent
every time this page is processed (i.e. one based on the location of allUIComponentTag
instances without anid
attribute set). - Ask the parent
UIComponent
for a child with this identifier. If not found, create one, callsetProperties()
with the new component as a parameter, and register it as a child with this identifier. Return the found or created childUIComponent
.
When creating a component, the process is:
- Retrieve the component type by calling
UIComponentTagBase.getComponentType()
- If the component has a
binding
attribute, create an expression from it, and callApplication.createComponent(java.lang.String)
with that expression, theFacesContext
, and the component type. Store the expression using the key"binding"
. - Otherwise, call
Application.createComponent(java.lang.String)
with only the component type. - Call
setProperties()
. - Add the new component as a child or facet of its parent
- Throws:
JspException
-
getParentUIComponentClassicTagBase
Locate and return the nearest enclosing
UIComponentClassicTagBase
if any; otherwise, returnnull
.- Parameters:
context
-PageContext
for the current page
-
getIndexOfNextChildTag
protected int getIndexOfNextChildTag()Description copied from class:UIComponentTagBase
Return the index of the next child to be added as a child of this tag. The default implementation maintains a list of created components and returns the size of the list.
- Specified by:
getIndexOfNextChildTag
in classUIComponentTagBase
-
addChild
Description copied from class:UIComponentTagBase
Add the component identifier of the specified
UIComponent
to the list of component identifiers created or located by nestedUIComponentTag
s processing this request.- Specified by:
addChild
in classUIComponentTagBase
- Parameters:
child
- New child whose identifier should be added
-
addFacet
Description copied from class:UIComponentTagBase
Add the facet name of the specified facet to the list of facet names created or located by nested
UIComponentTag
s processing this request.- Specified by:
addFacet
in classUIComponentTagBase
- Parameters:
name
- Facet name to be added
-
createVerbatimComponentFromBodyContent
Create a transient UIOutput component from the body content, of this tag instance or return null if there is no body content, the body content is whitespace, or the body content is a comment.
-
createVerbatimComponent
Use the
Application
instance to create a new component with the following characteristics.componentType
isjavax.faces.HtmlOutputText
.transient
istrue
.escape
isfalse
.id
isFacesContext.getViewRoot().createUniqueId()
-
addVerbatimBeforeComponent
protected void addVerbatimBeforeComponent(UIComponentClassicTagBase parentTag, UIComponent verbatim, UIComponent component) Add verbatim as a sibling of component in component in the parent's child list. verbatim is added to the list at the position immediatly preceding component.
-
addVerbatimAfterComponent
protected void addVerbatimAfterComponent(UIComponentClassicTagBase parentTag, UIComponent verbatim, UIComponent component) Add verbatim as a sibling of component in component in the parent's child list. verbatim is added to the list at the position immediatly following component.
-
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. Secondarily, cause a transientUIOutput
component to be created and placed in the tree before theUIComponent
instance for this tag. The value of thisUIOutput
component must include anything covered byCASE 1
orCASE 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 callingcreateVerbatimComponentFromBodyContent()
on the result. It then adds the returned component to the tree before the actual component for this tag instance instance by callingaddVerbatimBeforeComponent(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.- Specified by:
doStartTag
in interfaceTag
- Returns:
- EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY if it does not want to process it.
- Throws:
JspException
- if an error occurs- See Also:
-
doEndTag
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.- Retrieve from the
UIComponent
the set of component ids of child components created byUIComponentTag
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. - Retrieve from the
UIComponent
the set of facet names of facets created byUIComponentTag
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. - Release all references to the component, and pop it from the component stack for this response, removing the stack if this was the outermost component.
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.- Specified by:
doEndTag
in interfaceTag
- Returns:
- indication of whether to continue evaluating the JSP page.
- Throws:
JspException
- if an error occurs
- Retrieve from the
-
release
public void release()Release any resources allocated during the execution of this tag handler.
-
getDoAfterBodyValue
Return the flag value that should be returned from the
doAfterBody()
method when it is called. Subclasses may override this method to return the appropriate value.- Throws:
JspException
-
setBodyContent
Set the
bodyContent
for this tag handler. This method is invoked by the JSP page implementation object at most once per action invocation, beforedoInitiBody()
. This method will not be invoked for empty tags or for non-empty tags whosedoStartTag()
method returnsSKIP_BODY
orEVAL_BODY_INCLUDE
.- Specified by:
setBodyContent
in interfaceBodyTag
- Parameters:
bodyContent
- The newBodyContent
for this tag- See Also:
-
getPreviousOut
Get the
JspWriter
from ourBodyContent
. -
getBodyContent
-
doInitBody
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 whosedoStartTag()
method returnsSKIP_BODY
orEVAL_BODY_INCLUDE
.- Specified by:
doInitBody
in interfaceBodyTag
- Throws:
JspException
- if an error is encountered- See Also:
-
doAfterBody
Perform any processing necessary to handle the content implications of CASE 4 in the class description.
Return result from
getDoAfterBodyValue()
- Specified by:
doAfterBody
in interfaceIterationTag
- Returns:
- whether additional evaluations of the body are desired
- Throws:
JspException
- if an error is encountered
-
setId
Set the component identifier for our component. If the argument begins with
UIViewRoot.UNIQUE_ID_PREFIX
throw anIllegalArgumentException
- Specified by:
setId
in classUIComponentTagBase
- Parameters:
id
- The new component identifier. This may not start withUIViewRoot.UNIQUE_ID_PREFIX
.- Throws:
IllegalArgumentException
- if the argument is non-null
and starts withUIViewRoot.UNIQUE_ID_PREFIX
.
-
getId
Return the
id
value assigned by the page author. -
getFacesJspId
If this method has been called before on this tag's useful lifetime (before
release()
was called), return the previously returned value. Otherwise, ifgetJspId()
returns non-null
, prependUNIQUE_ID_PREFIX
to thejspId
and return the result. -
getCreatedComponents
Returns theList
ofUIComponent
ids created or located by nestedUIComponentTag
s while processing the current request. -
setJspId
Defined on
JspIdConsumer
. This method is called by the container beforedoStartTag()
. 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.
- Specified by:
setJspId
in interfaceJspIdConsumer
- Parameters:
id
- the container generated id for this tag, guaranteed to be unique within the page.
-
getJspId
-
setProperties
Override properties and attributes of the specified component, if the corresponding properties of this tag handler instance were explicitly set. This method must be called ONLY if the specified
UIComponent
was in fact created during the execution of this tag handler instance, and this call will occur BEFORE theUIComponent
is added to the view.Tag subclasses that want to support additional set properties must ensure that the base class
setProperties()
method is still called. A typical implementation that supports extra propertiesfoo
andbar
would look something like this:protected void setProperties(UIComponent component) { super.setProperties(component); if (foo != null) { component.setAttribute("foo", foo); } if (bar != null) { component.setAttribute("bar", bar); } }
The default implementation overrides the following properties:
rendered
- Set if a value for therendered
property is specified for this tag handler instance.rendererType
- Set if thegetRendererType()
method returns a non-null value.
- Parameters:
component
-UIComponent
whose properties are to be overridden
-
createComponent
protected abstract UIComponent createComponent(FacesContext context, String newId) throws JspException Create and return a new child component of the type returned by calling
getComponentType()
. If thisUIComponentTag
has a non-nullbinding
attribute, this is done by callApplication.createComponent(java.lang.String)
with the expression created for thebinding
attribute, and the expression will be stored on the component. Otherwise,Application.createComponent(java.lang.String)
is called with only the component type. Finally, initialize the components id and other properties.- Parameters:
context
-FacesContext
for the current requestnewId
- id of the component- Throws:
JspException
-
hasBinding
protected abstract boolean hasBinding()Return
true
if this component has a non-null
binding attribute. This method is necessary to allow subclasses that expose thebinding
property as an Faces 1.1 style EL property as well as subclasses that expose it as an EL API property. -
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 ofdoStartTag()
anddoEndTag()
on this tag instance.- Specified by:
getComponentInstance
in classUIComponentTagBase
-
getCreated
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 ofdoStartTag()
anddoEndTag()
on this tag instance.- Specified by:
getCreated
in classUIComponentTagBase
-
getFacesContext
Description copied from class:UIComponentTagBase
Return the
FacesContext
instance for the current request. This value will be non-null
only from the beginning ofdoStartTag()
through the end ofdoEndTag()
for each tag instance.- Specified by:
getFacesContext
in classUIComponentTagBase
-
getFacetName
Return the facet name that we should be stored under, if any; otherwise, return null (indicating that we will be a child component).
-