javax.faces.webapp

Class UIComponentClassicTagBase

java.lang.Object

javax.faces.webapp.UIComponentTagBase

javax.faces.webapp.UIComponentClassicTagBase

All Implemented Interfaces:

javax.servlet.jsp.tagext.BodyTag, javax.servlet.jsp.tagext.IterationTag, javax.servlet.jsp.tagext.JspIdConsumer, javax.servlet.jsp.tagext.JspTag, javax.servlet.jsp.tagext.Tag

Direct Known Subclasses:

UIComponentELTag, UIComponentTag

public abstract class UIComponentClassicTagBase
extends UIComponentTagBase
implements javax.servlet.jsp.tagext.JspIdConsumer, javax.servlet.jsp.tagext.BodyTag

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

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

Constructors

Constructor and Description
UIComponentClassicTagBase()

Method Summary

Methods

Modifier and Type	Method and Description
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.
javax.servlet.jsp.tagext.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.
String	getJspId()
javax.servlet.jsp.tagext.Tag	getParent() Return the Tag that is the parent of this instance.
static UIComponentClassicTagBase	getParentUIComponentClassicTagBase(javax.servlet.jsp.PageContext context) Locate and return the nearest enclosing UIComponentClassicTagBase if any; otherwise, return null.
javax.servlet.jsp.JspWriter	getPreviousOut() Get the JspWriter from our BodyContent.
void	release() Release any resources allocated during the execution of this tag handler.
void	setBodyContent(javax.servlet.jsp.tagext.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(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.

Methods inherited from class javax.faces.webapp.UIComponentTagBase

getComponentType, getRendererType

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

UIComponentClassicTagBase

public UIComponentClassicTagBase()

Method Detail

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

getParentUIComponentClassicTagBase

public static UIComponentClassicTagBase getParentUIComponentClassicTagBase(javax.servlet.jsp.PageContext context)

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

Parameters:

context - PageContext for the current page

doStartTag

public int doStartTag()
               throws javax.servlet.jsp.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.

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

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

setBodyContent

public void setBodyContent(javax.servlet.jsp.tagext.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.

Specified by:

setBodyContent in interface javax.servlet.jsp.tagext.BodyTag

Parameters:

bodyContent - The new BodyContent for this tag

getPreviousOut

public javax.servlet.jsp.JspWriter getPreviousOut()

Get the JspWriter from our BodyContent.

getBodyContent

public javax.servlet.jsp.tagext.BodyContent getBodyContent()

doInitBody

public void doInitBody()
                throws javax.servlet.jsp.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.

Specified by:

doInitBody in interface javax.servlet.jsp.tagext.BodyTag

Throws:

javax.servlet.jsp.JspException - if an error is encountered

doAfterBody

public int doAfterBody()
                throws javax.servlet.jsp.JspException

Perform any processing necessary to handle the content implications of CASE 4 in the class description.

Return result from getDoAfterBodyValue()

Specified by:

doAfterBody in interface javax.servlet.jsp.tagext.IterationTag

Throws:

javax.servlet.jsp.JspException - if an error is encountered

setId

public void setId(String id)

Set the component identifier for our component. If the argument begins with UIViewRoot.UNIQUE_ID_PREFIX throw an IllegalArgumentException

Specified by:

setId in class UIComponentTagBase

Parameters:

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

Throws:

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

setJspId

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.

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

Parameters:

id - the container generated id for this tag, guaranteed to be unique within the page.

getJspId

public String getJspId()

getComponentInstance

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.

Specified by:

getComponentInstance in class UIComponentTagBase

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.

Specified by:

getCreated in class UIComponentTagBase