javax.faces.webapp
Class UIComponentTag

java.lang.Object
  javax.faces.webapp.UIComponentTag

All Implemented Interfaces:

JspTag, Tag

Direct Known Subclasses:

FacesTag, UIComponentBodyTag

public abstract class UIComponentTag

extends java.lang.Object

implements Tag

UIComponentTag is a 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.

The id attribute of a UIComponentTag is used to set the componentId property of the UIComponent associated with this tag.

Field Summary

protected FacesContext	context The FacesContext for the request being processed, if any.
protected java.lang.String	id The component identifier for the associated component.
protected PageContext	pageContext The JSP PageContext for the page we are embedded in.
protected boolean	rendered An override for the rendered attribute associated with our UIComponent, if not true.
protected boolean	renderedSet Flag indicating whether the rendered attribute was set on this tag instance.

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 UIComponent	findComponent(FacesContext context) Find and return the UIComponent, from the component tree, that corresponds to this tag handler instance.
protected int	getChildIndex() Return the current index into the children of this tag's corresponding UIComponent.
UIComponent	getComponent() Return the UIComponent instance that is associated with this tag instance.
protected abstract java.lang.String	getComponentType() Returns the componentType 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 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).
Tag	getParent() Return the Tag that is the parent of this instance.
protected UIComponentTag	getParentUIComponentTag() 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 void	incrementChildIndex() Increment the index into the children of this tag's component.
protected boolean	isSuppressed() Return true if rendering should be suppressed because our component is a facet, or some parent component has been configured with getRendersChildren() as true.
protected void	overrideProperties(UIComponent component) Override properties of the specified component if the corresponding properties of this tag handler were explicitly set, and the corresponding attribute of the component is not set.
void	release() Release any resources allocated during the execution of this tag handler.
void	setId(java.lang.String id) Set the component identifier for our component.
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.
void	setRendered(boolean 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

context

protected FacesContext context

The FacesContext for the request being processed, if any.

pageContext

protected PageContext pageContext

The JSP PageContext for the page we are embedded in.

id

protected java.lang.String id

The component identifier for the associated component.

rendered

protected boolean rendered

An override for the rendered attribute associated with our UIComponent, if not true.

renderedSet

protected boolean renderedSet

Flag indicating whether the rendered attribute was set on this tag instance.

Constructor Detail

UIComponentTag

public UIComponentTag()

Method Detail

setId

public void setId(java.lang.String id)

Set the component identifier for our component.

Parameters:

id - The new component identifier

setRendered

public void setRendered(boolean rendered)

Set an override for the rendered attribute.

Parameters:

rendered - The new value for rendered attribute

getComponentType

protected abstract java.lang.String getComponentType()

Returns the componentType for the component that is or will be bound to this tag.

Returns:

the componentType for this tag instance. This value can be plugged into Application.getComponent(java.lang.String) to create the UIComponent instance for this tag.

getComponent

public UIComponent getComponent()

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.

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 of doStartTag() and doEndTag() on this tag instance.

getRendererType

public 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.

setPageContext

public void setPageContext(PageContext pageContext)

Set the PageContext of the page containing this tag instance.

Specified by:

setPageContext in interface Tag

Parameters:

pageContext - The enclosing PageContext

getParent

public Tag getParent()

Return the Tag that is the parent of this instance.

Specified by:

getParent in interface Tag

Returns:

the current parent, or null if none.

See Also:

TagSupport.findAncestorWithClass(javax.servlet.jsp.tagext.Tag, java.lang.Class)

setParent

public void setParent(Tag parent)

Set the Tag that is the parent of this instance. In addition, locate the closest enclosing UIComponentTag and increment its numChildren counter. Finally, save our childIndex as (enclosingUIComponentTag.numChildren - 1).

Specified by:

setParent in interface Tag

Parameters:

parent - The new parent Tag

doStartTag

public int doStartTag()
               throws JspException

Render the beginning of the UIComponent that is associated with this tag (via the id attribute), by following these steps.

• Ensure that an appropriate ResponseWriter is associated with the current FacesContext. This ensures that encoded output from the components is routed through the JspWriter for the current page.
• Locate the component (in the component tree) corresponding to this tag, creating a new one if necesary.
• Override the attributes of the associated component with values set in our custom tag attributes, if values for the corresponding attributes are NOT already set on the component.
• Push this component onto the stack of components corresponding to nested component tags for the current response, creating the stack if necessary.
• Call the encodeBegin() method of the component, unless rendering is suppressed or our component renders its own children.

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 interface Tag

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:

BodyTag

doEndTag

public int doEndTag()
             throws JspException

Render the ending of the UIComponent that is associated with this tag (via the id attribute), by following these steps.

• If the rendersChildren property of this component is true, call the encodeBegin() method of this component.
• If the rendersChildren property of this component is true, call the encodeChildren() method of the component.
• Call the encodeEnd() method of the component.
• 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 interface Tag

Returns:

indication of whether to continue evaluating the JSP page.

Throws:

JspException - if an error occurs

release

public void release()

Release any resources allocated during the execution of this tag handler.

Specified by:

release in interface Tag

encodeBegin

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.

Throws:

java.io.IOException - if an input/output error occurs

encodeChildren

protected 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.

Throws:

java.io.IOException - if an input/output error occurs

encodeEnd

protected 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.

Throws:

java.io.IOException - if an input/output error occurs

findComponent

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 by calling getComponent(), and add it is a child or facet of the UIComponent associated with our nearest enclosing UIComponentTag.

Throws:

JspException

getChildIndex

protected int getChildIndex()

Return the current index into the children of this tag's corresponding UIComponent.

getDoEndValue

protected 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.

Throws:

JspException - to cause doEnd() to throw an exception

getDoStartValue

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.

Throws:

JspException - to cause doStart() to throw an exception

getFacetName

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).

getParentUIComponentTag

protected UIComponentTag getParentUIComponentTag()

Locate and return the nearest enclosing UIComponentTag if any; otherwise, return null.

incrementChildIndex

protected void incrementChildIndex()

Increment the index into the children of this tag's component.

isSuppressed

protected boolean isSuppressed()

Return true if rendering should be suppressed because our component is a facet, or some parent component has been configured with getRendersChildren() as true.

overrideProperties

protected void overrideProperties(UIComponent component)

Override properties of the specified component if the corresponding properties of this tag handler were explicitly set, and the corresponding attribute of the component is not set.

Tag subclasses that want to support additional override properties must ensure that the base class overrideProperties() method is still called. A typical implementation that supports extra properties foo and bar would look something like this:

 protected void overrideProperties(UIComponent component) {
   super.overrideProperties(component);
   if (foo != null) {
     component.setAttribute("foo", foo);
   }
   if (bar != null) {
     component.setAttribute("bar", bar);
   }
 }
 

setupResponseWriter

protected void setupResponseWriter()

Set up the ResponseWriter for the current response, if this has not been done already.