|
Java EE 5 SDK | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object javax.faces.webapp.UIComponentTagBase javax.faces.webapp.UIComponentClassicTagBase
public abstract class UIComponentClassicTagBase
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 | |
---|---|
protected BodyContent |
bodyContent
The bodyContent for this tag handler. |
protected PageContext |
pageContext
The JSP PageContext for the page we are embedded in. |
protected static String |
UNIQUE_ID_PREFIX
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 | |
---|---|
UIComponentClassicTagBase()
|
Method Summary | |
---|---|
protected void |
addChild(UIComponent child)
Add the component identifier of the specified UIComponent
to the list of component identifiers created or located by nested
UIComponentTag s processing this request. |
protected void |
addFacet(String name)
Add the facet name of the specified facet to the list of facet names created or located by nested UIComponentTag 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 calling getComponentType() . |
protected UIOutput |
createVerbatimComponent()
Use the Application instance to create a new component
with the following characteristics. |
protected UIComponent |
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. |
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. |
protected void |
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. |
protected void |
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. |
protected void |
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. |
protected UIComponent |
findComponent(FacesContext context)
Find and return the UIComponent , from the component
tree, that corresponds to this tag handler instance. |
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. |
protected List<String> |
getCreatedComponents()
Returns the List of UIComponent ids created or
located by nested UIComponentTag s while processing the current
request. |
protected int |
getDoAfterBodyValue()
Return the flag value that should be returned from the doAfterBody() method when it is called. |
protected int |
getDoEndValue()
Return the flag value that should be returned from the doEnd() method when it is called. |
protected int |
getDoStartValue()
Return the flag value that should be returned from the doStart() method when it is called. |
protected FacesContext |
getFacesContext()
Return the FacesContext instance for the current
request. |
protected String |
getFacesJspId()
If this method has been called before on this tag's useful lifetime (before release() was called), return the
previously returned value. |
protected String |
getFacetName()
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 the id value assigned by the page author. |
protected int |
getIndexOfNextChildTag()
Return the index of the next child to be added as a child of this tag. |
String |
getJspId()
|
Tag |
getParent()
Return the Tag that is the parent of this instance. |
static UIComponentClassicTagBase |
getParentUIComponentClassicTagBase(PageContext context)
Locate and return the nearest enclosing UIComponentClassicTagBase
if any; otherwise, return null . |
JspWriter |
getPreviousOut()
Get the JspWriter from our BodyContent . |
protected abstract boolean |
hasBinding()
Return true 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 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(PageContext pageContext)
Set the PageContext of the page containing this
tag instance. |
void |
setParent(Tag parent)
Set the Tag 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 |
setupResponseWriter()
Set up the ResponseWriter for the
current response, if this has not been done already. |
Methods inherited from class javax.faces.webapp.UIComponentTagBase |
---|
getComponentType, getELContext, getRendererType |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
---|
protected static final String UNIQUE_ID_PREFIX
protected BodyContent bodyContent
The bodyContent
for this tag handler.
protected PageContext pageContext
The JSP PageContext
for the page we are embedded in.
Constructor Detail |
---|
public UIComponentClassicTagBase()
Method Detail |
---|
protected int getDoStartValue() throws JspException
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.
JspException
- to cause doStart()
to
throw an exceptionprotected int getDoEndValue() throws JspException
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.
JspException
- to cause doEnd()
to
throw an exceptionprotected void encodeBegin() throws IOException
Delegate to the encodeBegin()
method of our
corresponding UIComponent
. This method is called from
doStartTag()
. Normally, delegation occurs unconditionally;
however, this method is abstracted out so that advanced tags can
conditionally perform this call.
IOException
- if an input/output error occursprotected void encodeChildren() throws IOException
Delegate to the encodeChildren()
method of our
corresponding UIComponent
. This method is called from
doStartTag()
. Normally, delegation occurs unconditionally;
however, this method is abstracted out so that advanced tags can
conditionally perform this call.
IOException
- if an input/output error occursprotected void encodeEnd() throws IOException
Delegate to the encodeEnd()
method of our
corresponding UIComponent
. This method is called from
doStartTag()
. Normally, delegation occurs unconditionally;
however, this method is abstracted out so that advanced tags can
conditionally perform this call.
IOException
- if an input/output error occurspublic void setPageContext(PageContext pageContext)
Set the PageContext
of the page containing this
tag instance.
setPageContext
in interface Tag
pageContext
- The enclosing PageContext
public Tag getParent()
Return the Tag
that is the parent of this instance.
TagSupport.findAncestorWithClass(javax.servlet.jsp.tagext.Tag, java.lang.Class)
public void setParent(Tag parent)
Set the Tag
that is the parent of this instance.
parent
- The new parent Tag
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.
protected UIComponent findComponent(FacesContext context) throws JspException
Find and return the UIComponent
, from the component
tree, that corresponds to this tag handler instance. If there
is no such UIComponent
, create one
and add it as a child or facet of the UIComponent
associated
with our nearest enclosing UIComponentTag
. The process for
locating or creating the component is:
UIComponentTag
instance, and ask it for its component.
If there is no parent UIComponentTag
instance, this tag
represents the root component, so get it from the current
Tree
and return it.UIComponentTag
instance has the
facetName
attribute set, ask the parent
UIComponent
for a facet with this name. If not found,
create one, call setProperties()
with the new
component as a parameter, and register it under this name.
Return the found or created facet UIComponent
.UIComponentTag
has
an id
attribute set, use that value; otherwise,
generate an identifier that is guaranteed to be the same for
this UIComponent
every time this page is processed
(i.e. one based on the location of all UIComponentTag
instances without an id
attribute set).UIComponent
for a child with this identifier.
If not found, create one, call setProperties()
with the new component as a parameter, and register it as a child
with this identifier. Return the found or created
child UIComponent
.When creating a component, the process is:
UIComponentTagBase.getComponentType()
binding
attribute,
create an expression from it, and call
Application.createComponent(java.lang.String)
with that expression,
the FacesContext
, and the component type. Store the
expression using the key "binding"
.Application.createComponent(java.lang.String)
with
only the component type.
setProperties()
.
JspException
public static UIComponentClassicTagBase getParentUIComponentClassicTagBase(PageContext context)
Locate and return the nearest enclosing UIComponentClassicTagBase
if any; otherwise, return null
.
context
- PageContext
for the current pageprotected int getIndexOfNextChildTag()
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.
getIndexOfNextChildTag
in class UIComponentTagBase
protected void addChild(UIComponent child)
UIComponentTagBase
Add the component identifier of the specified UIComponent
to the list of component identifiers created or located by nested
UIComponentTag
s processing this request.
addChild
in class UIComponentTagBase
child
- New child whose identifier should be addedprotected void addFacet(String name)
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.
addFacet
in class UIComponentTagBase
name
- Facet name to be addedprotected UIComponent 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.
protected UIOutput createVerbatimComponent()
Use the Application
instance to create a new component
with the following characteristics.
componentType
is
javax.faces.HtmlOutputText
.
transient
is true
.
escape
is false
.
id
is
FacesContext.getViewRoot().createUniqueId()
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.
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.
public int doStartTag() throws 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 Tag
JspException
- if an error occursBodyTag
public int doEndTag() throws 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.
JspException
- if an error occurspublic void release()
Release any resources allocated during the execution of this tag handler.
protected int getDoAfterBodyValue() throws JspException
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.
JspException
public void setBodyContent(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 BodyTag
bodyContent
- The new BodyContent
for this tagBodyTag.doInitBody()
,
IterationTag.doAfterBody()
public JspWriter getPreviousOut()
Get the JspWriter
from our BodyContent
.
public BodyContent getBodyContent()
public void doInitBody() throws 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 BodyTag
JspException
- if an error is encounteredIterationTag.doAfterBody()
public int doAfterBody() throws JspException
Perform any processing necessary to handle the content implications of CASE 4 in the class description.
Return result from getDoAfterBodyValue()
doAfterBody
in interface IterationTag
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
.protected String getId()
Return the id
value assigned by the page author.
protected String getFacesJspId()
If this method has been called before on this tag's useful
lifetime (before release()
was called), return the
previously returned value. Otherwise, if getJspId()
returns non-null
, prepend UNIQUE_ID_PREFIX
to the jspId
and return the result.
protected List<String> getCreatedComponents()
List
of UIComponent
ids created or
located by nested UIComponentTag
s while processing the current
request.
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.
setJspId
in interface JspIdConsumer
id
- the container generated id for this tag, guaranteed to
be unique within the page.public String getJspId()
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. 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 the UIComponent
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 properties foo
and bar
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 the
rendered
property is specified for
this tag handler instance.rendererType
- Set if the getRendererType()
method returns a non-null value.
component
- UIComponent
whose properties are to be
overriddenprotected abstract UIComponent createComponent(FacesContext context, String newId) throws JspException
Create and return a new child component of the type returned
by calling getComponentType()
. If this UIComponentTag
has a non-null binding
attribute,
this is done by call Application.createComponent(java.lang.String)
with the
expression created for the binding
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.
context
- FacesContext
for the current requestnewId
- id of the component
JspException
protected abstract boolean hasBinding()
Return true
if this component has a
non-null
binding attribute. This method is
necessary to allow subclasses that expose the
binding
property as an Faces 1.1 style EL property
as well as subclasses that expose it as an EL API property.
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
protected FacesContext getFacesContext()
UIComponentTagBase
Return the FacesContext
instance for the current
request. This value will be non-null
only from the
beginning of doStartTag()
through the end of
doEndTag()
for each tag instance.
getFacesContext
in class UIComponentTagBase
protected String getFacetName()
Return the facet name that we should be stored under, if any; otherwise, return null (indicating that we will be a child component).
|
Java EE 5 SDK | ||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Copyright 2006 Sun Microsystems, Inc. All rights reserved.