|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.faces.webapp.UIComponentTag
UIComponentTag
is the base class for all JSP custom
actions that correspond to user interface components in a page that is
rendered by JavaServer Faces. Tags that need to process their tag bodies
should subclass UIComponentBodyTag
instead.
Field Summary | |
protected javax.servlet.jsp.PageContext |
pageContext
The JSP PageContext for the page we are embedded in. |
Fields inherited from interface javax.servlet.jsp.tagext.Tag |
EVAL_BODY_INCLUDE, EVAL_PAGE, SKIP_BODY, SKIP_PAGE |
Constructor Summary | |
UIComponentTag()
|
Method Summary | |
int |
doEndTag()
Render the ending of the UIComponent that is associated
with this tag (via the id attribute), by following these
steps. |
int |
doStartTag()
Render the beginning of the UIComponent that is associated
with this tag (via the id attribute), by following these
steps. |
protected void |
encodeBegin()
Delegate to the encodeBegin() method of our
corresponding UIComponent . |
protected void |
encodeChildren()
Delegate to the encodeChildren() method of our
corresponding UIComponent . |
protected void |
encodeEnd()
Delegate to the encodeEnd() method of our
corresponding UIComponent . |
protected javax.faces.component.UIComponent |
findComponent(javax.faces.context.FacesContext context)
Find and return the UIComponent , from the component
tree, that corresponds to this tag handler instance. |
javax.faces.component.UIComponent |
getComponentInstance()
Return the UIComponent instance that is associated with
this tag instance. |
abstract java.lang.String |
getComponentType()
Return the component type for the component that is or will be bound to this tag. |
boolean |
getCreated()
Return true if we dynamically created a new component
instance during execution of this tag. |
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 javax.faces.context.FacesContext |
getFacesContext()
Return the FacesContext instance for the current
request. |
protected java.lang.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 java.lang.String |
getId()
Return the id value assigned by the page author. |
javax.servlet.jsp.tagext.Tag |
getParent()
Return the Tag that is the parent of this instance. |
static javax.faces.webapp.UIComponentTag |
getParentUIComponentTag(javax.servlet.jsp.PageContext context)
Locate and return the nearest enclosing UIComponentTag if any;
otherwise, return null . |
abstract java.lang.String |
getRendererType()
Return the rendererType property that selects the
Renderer to be used for encoding this component, or
null to ask the component to render itself directly. |
protected boolean |
isSuppressed()
Return true if rendering should be suppressed because
of any of the follow reasons. |
static boolean |
isValueReference(java.lang.String value)
Return true if the specified value conforms to the
syntax requirements of a value binding expression. |
void |
release()
Release any resources allocated during the execution of this tag handler. |
void |
setBinding(java.lang.String binding)
Set the value binding expression for our component. |
void |
setId(java.lang.String id)
Set the component identifier for our component. |
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. |
protected void |
setProperties(javax.faces.component.UIComponent component)
Override properties and attributes of the specified component, if the corresponding properties of this tag handler instance were explicitly set. |
void |
setRendered(java.lang.String rendered)
Set an override for the rendered attribute. |
protected void |
setupResponseWriter()
Set up the ResponseWriter for the current response,
if this has not been done already. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
protected javax.servlet.jsp.PageContext pageContext
The JSP PageContext
for the page we are embedded in.
Constructor Detail |
public UIComponentTag()
Method Detail |
public void setBinding(java.lang.String binding) throws javax.servlet.jsp.JspException
Set the value binding expression for our component.
binding
- The new value binding expression
java.lang.IllegalArgumentException
- if the specified binding is not a
valid value binding expression.
javax.servlet.jsp.JspException
public void setId(java.lang.String id)
Set the component identifier for our component. If the
argument begins with UIViewRoot.UNIQUE_ID_PREFIX
throw an
IllegalArgumentException
id
- The new component identifier. This may not start with
UIViewRoot.UNIQUE_ID_PREFIX
.
java.lang.IllegalArgumentException
- if the argument is
non-null
and starts with UIViewRoot.UNIQUE_ID_PREFIX
.public void setRendered(java.lang.String rendered)
Set an override for the rendered attribute.
rendered
- The new value for rendered attributepublic abstract java.lang.String getComponentType()
Return the component type for the component that is or will be
bound to this tag. This value can be passed to
Application.createComponent(java.lang.String)
to create
the UIComponent
instance for this tag. Subclasses must
override this method to return the appropriate value.
public javax.faces.component.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.
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.
public static javax.faces.webapp.UIComponentTag getParentUIComponentTag(javax.servlet.jsp.PageContext context)
Locate and return the nearest enclosing UIComponentTag
if any;
otherwise, return null
.
context
- PageContext
for the current pagepublic abstract java.lang.String getRendererType()
Return the rendererType
property that selects the
Renderer
to be used for encoding this component, or
null
to ask the component to render itself directly.
Subclasses must override this method to return the appropriate value.
public static boolean isValueReference(java.lang.String value)
Return true
if the specified value conforms to the
syntax requirements of a value binding expression. Such expressions
may be used on most component tag attributes to signal a desire for
deferred evaluation of the attribute or property value to be set on
the underlying UIComponent
.
value
- The value to evaluate
java.lang.NullPointerException
- if value
is
null
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 int doStartTag() throws javax.servlet.jsp.JspException
Render the beginning of the UIComponent
that is associated
with this tag (via the id
attribute), by following these
steps.
ResponseWriter
is associated
with the current FacesContext
. This ensures that encoded
output from the components is routed through the
JspWriter
for the current page.UIComponentTag
is nested within the body of
another UIComponentTag
, call its addChild
method to save the component identifier for the UIComponent
that corresponds to this UIComponentTag
.findComponent()
to locate the UIComponent
instance associated wth this UIComponentTag
, creating a new
one if necessary.encodeBegin()
method of the component,
unless rendering is suppressed or our component renders its
own children; if encodeBegin()
is called,
ResponseWriter.flush()
must also be called.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
Render the ending of the UIComponent
that is associated
with this tag (via the id
attribute), by following these
steps.
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.rendersChildren
property of this component is
true
, call the encodeBegin()
method
of this component.
rendersChildren
property of this component is
true
, call the encodeChildren()
method
of the component.encodeEnd()
method of the 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.
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
protected void encodeBegin() throws java.io.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.
java.io.IOException
- if an input/output error occursprotected void encodeChildren() throws java.io.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.
java.io.IOException
- if an input/output error occursprotected void encodeEnd() throws java.io.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.
java.io.IOException
- if an input/output error occursprotected javax.faces.component.UIComponent findComponent(javax.faces.context.FacesContext context) throws javax.servlet.jsp.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:
getComponentType()
binding
attribute,
create a ValueBinding
from it, and call
Application.createComponent(java.lang.String)
with that ValueBinding
,
the FacesContext
, and the component type. Store the
ValueBinding
using the key "binding"
and
UIComponent.setValueBinding(java.lang.String, javax.faces.el.ValueBinding)
.Application.createComponent(java.lang.String)
with
only the component type.
setProperties()
.
javax.servlet.jsp.JspException
protected int getDoEndValue() throws javax.servlet.jsp.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.
javax.servlet.jsp.JspException
- to cause doEnd()
to
throw an exceptionprotected int getDoStartValue() throws javax.servlet.jsp.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.
javax.servlet.jsp.JspException
- to cause doStart()
to
throw an exceptionprotected javax.faces.context.FacesContext getFacesContext()
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.
protected java.lang.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 java.lang.String getId()
Return the id
value assigned by the page author.
protected boolean isSuppressed()
Return true
if rendering should be suppressed because
of any of the follow reasons.
rendered
property set
to false
.rendersChildren
is true
.
protected void setProperties(javax.faces.component.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 void setupResponseWriter()
Set up the ResponseWriter
for the current response,
if this has not been done already.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |