javax.faces.webapp
Class UIComponentTag

java.lang.Object
  |
  +--javax.faces.webapp.UIComponentTag

All Implemented Interfaces:

javax.servlet.jsp.tagext.JspTag, javax.servlet.jsp.tagext.Tag

Direct Known Subclasses:

UIComponentBodyTag

public abstract class UIComponentTag

extends java.lang.Object

implements javax.servlet.jsp.tagext.Tag

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

pageContext

protected javax.servlet.jsp.PageContext pageContext

The JSP PageContext for the page we are embedded in.

Constructor Detail

UIComponentTag

public UIComponentTag()

Method Detail

setBinding

public void setBinding(java.lang.String binding)
                throws javax.servlet.jsp.JspException

Set the value binding expression for our component.

Parameters:

binding - The new value binding expression

Throws:

java.lang.IllegalArgumentException - if the specified binding is not a valid value binding expression.

javax.servlet.jsp.JspException

setId

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

Parameters:

id - The new component identifier. This may not start with UIViewRoot.UNIQUE_ID_PREFIX.

Throws:

java.lang.IllegalArgumentException - if the argument is non-null and starts with UIViewRoot.UNIQUE_ID_PREFIX.

setRendered

public void setRendered(java.lang.String rendered)

Set an override for the rendered attribute.

Parameters:

rendered - The new value for rendered attribute

getComponentType

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

getComponentInstance

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.

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.

getParentUIComponentTag

public static javax.faces.webapp.UIComponentTag getParentUIComponentTag(javax.servlet.jsp.PageContext context)

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

Parameters:

context - PageContext for the current page

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.

isValueReference

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.

Parameters:

value - The value to evaluate

Throws:

java.lang.NullPointerException - if value is null

setPageContext

public void setPageContext(javax.servlet.jsp.PageContext pageContext)

Set the PageContext of the page containing this tag instance.

Specified by:

setPageContext in interface javax.servlet.jsp.tagext.Tag

Parameters:

pageContext - The enclosing PageContext

getParent

public javax.servlet.jsp.tagext.Tag getParent()

Return the Tag that is the parent of this instance.

Specified by:

getParent in interface javax.servlet.jsp.tagext.Tag

setParent

public void setParent(javax.servlet.jsp.tagext.Tag parent)

Set the Tag that is the parent of this instance.

Specified by:

setParent in interface javax.servlet.jsp.tagext.Tag

Parameters:

parent - The new parent Tag

doStartTag

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.

• 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 view) corresponding to this tag, creating a new one if necesary.
• If this 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.
• Call findComponent() to locate the UIComponent instance associated wth this UIComponentTag, creating a new one if necessary.
• Call the 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.

Specified by:

doStartTag in interface javax.servlet.jsp.tagext.Tag

Throws:

javax.servlet.jsp.JspException - if an error occurs

doEndTag

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

• Retrieve from the 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.
• Retrieve from the 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.
• 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 javax.servlet.jsp.tagext.Tag

Throws:

javax.servlet.jsp.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 javax.servlet.jsp.tagext.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 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:

1. If we have previously located this component, return it.
2. Locate the parent component by looking for a parent 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.
3. If this 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.
4. Determine the component id to be assigned to the new component, as follows: if this 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).
5. Ask the parent 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:

1. Retrieve the component type by calling getComponentType()
2. If the component has a 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).
3. Otherwise, call Application.createComponent(java.lang.String) with only the component type.
4. Call setProperties().
5. Add the new component as a child or facet of its parent

javax.servlet.jsp.JspException

getDoEndValue

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.

Throws:

javax.servlet.jsp.JspException - to cause doEnd() to throw an exception

getDoStartValue

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

Throws:

javax.servlet.jsp.JspException - to cause doStart() to throw an exception

getFacesContext

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

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

getId

protected java.lang.String getId()

Return the id value assigned by the page author.

isSuppressed

protected boolean isSuppressed()

Return true if rendering should be suppressed because of any of the follow reasons.

• The component is a facet (whose rendering, if any), is always the responsibility of the owing component.
• The component has its rendered property set to false.
• The component is a child of a parent whose rendersChildren is true.
• The component is a child of a parent whose rendering is itself suppressed.

setProperties

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:

• componentId - Set if a value for the id property is specified for this tag handler instance.
• component - Set if a value for the component property is specified for this tag handler instance.
• rendered - Set if a value for the rendererd property is specified for this tag handler instance.
• rendererType - Set if the getRendererType() method returns a non-null value.

Parameters:

component - UIComponent whose properties are to be overridden

setupResponseWriter

protected void setupResponseWriter()

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