javax.faces.webapp
Class UIComponentTag

java.lang.Object
  extended by javax.faces.webapp.UIComponentTag
All Implemented Interfaces:
javax.servlet.jsp.tagext.Tag
Direct Known Subclasses:
UIComponentBodyTag

public abstract class UIComponentTag
extends Object
implements javax.servlet.jsp.tagext.Tag

Base class for all JSP tags that represent a JSF UIComponent.

Disclaimer: The official definition for the behaviour of this class is the JSF specification but for legal reasons the specification cannot be replicated here. Any javadoc present on this class therefore describes the current implementation rather than the officially required behaviour, though it is believed that this class does comply with the specification. see Javadoc of JSF Specification for more.

Version:
$Revision: 826571 $ $Date: 2009-10-18 20:23:46 -0500 (Sun, 18 Oct 2009) $
Author:
Manfred Geiler (latest modification by $Author: lu4242 $)

Field Summary
protected  javax.servlet.jsp.PageContext pageContext
           
 
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()
          Invoked by the standard jsp processing mechanism when the closing tag of a JSF component element is found.
 int doStartTag()
          Invoked by the standard jsp processing mechanism when the opening tag of a JSF component element is found.
protected  void encodeBegin()
          Invoke encodeBegin on the associated UIComponent.
protected  void encodeChildren()
          Invoke encodeChildren on the associated UIComponent.
protected  void encodeEnd()
          Invoke encodeEnd on the associated UIComponent.
protected  UIComponent findComponent(FacesContext context)
          Return the corresponding UIComponent for this tag, creating it if necessary.
 UIComponent getComponentInstance()
          Return the UIComponent instance associated with this tag.
abstract  String getComponentType()
          Specify the "component type name" used together with the component's family and the Application object to create a UIComponent instance for this tag.
 boolean getCreated()
          Return true if this tag created the associated UIComponent (rather than locating an existing instance of the UIComponent in the view).
protected  int getDoEndValue()
          Get the value to be returned by the doEndTag method to the JSP framework.
protected  int getDoStartValue()
          Get the value to be returned by the doStartTag method to the JSP framework.
protected  FacesContext getFacesContext()
           
protected  String getFacetName()
           
protected  String getId()
          Return the id (if any) specified as an xml attribute on this tag.
 javax.servlet.jsp.tagext.Tag getParent()
          Returns the enclosing JSP tag object.
static UIComponentTag getParentUIComponentTag(javax.servlet.jsp.PageContext pageContext)
          Return the nearest JSF tag that encloses this tag.
abstract  String getRendererType()
          Specify the "renderer type name" used together with the current renderKit to get a Renderer instance for the corresponding UIComponent.
protected  boolean isSuppressed()
          Determine whether this component renders itself.
static boolean isValueReference(String value)
          Return true if the specified string contains an EL expression.
 void release()
           
 void setBinding(String binding)
          Setter for common JSF xml attribute "binding".
 void setId(String id)
          Setter for common JSF xml attribute "id".
 void setPageContext(javax.servlet.jsp.PageContext pageContext)
          Standard method invoked by the JSP framework to inform this tag of the PageContext associated with the jsp page currently being processed.
 void setParent(javax.servlet.jsp.tagext.Tag parent)
          Standard method invoked by the JSP framework to inform this tag of the enclosing JSP tag object.
protected  void setProperties(UIComponent component)
           
 void setRendered(String rendered)
          Setter for common JSF xml attribute "rendered".
protected  void setupResponseWriter()
           
 
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
Constructor Detail

UIComponentTag

public UIComponentTag()
Method Detail

release

public void release()
Specified by:
release in interface javax.servlet.jsp.tagext.Tag

setBinding

public void setBinding(String binding)
                throws javax.servlet.jsp.JspException
Setter for common JSF xml attribute "binding".

Throws:
javax.servlet.jsp.JspException

setId

public void setId(String id)
Setter for common JSF xml attribute "id".


getId

protected String getId()
Return the id (if any) specified as an xml attribute on this tag.


setRendered

public void setRendered(String rendered)
Setter for common JSF xml attribute "rendered".


getComponentType

public abstract String getComponentType()
Specify the "component type name" used together with the component's family and the Application object to create a UIComponent instance for this tag. This method is called by other methods in this class, and is intended to be overridden in subclasses to specify the actual component type to be created.

Returns:
a registered component type name, never null.

getComponentInstance

public UIComponent getComponentInstance()
Return the UIComponent instance associated with this tag.

Returns:
a UIComponent, never null.

getCreated

public boolean getCreated()
Return true if this tag created the associated UIComponent (rather than locating an existing instance of the UIComponent in the view).


getParentUIComponentTag

public static UIComponentTag getParentUIComponentTag(javax.servlet.jsp.PageContext pageContext)
Return the nearest JSF tag that encloses this tag.


getRendererType

public abstract String getRendererType()
Specify the "renderer type name" used together with the current renderKit to get a Renderer instance for the corresponding UIComponent.

A JSP tag can return null here to use the default renderer type string. If non-null is returned, then the UIComponent's setRendererType method will be called passing this value, and this will later affect the type of renderer object returned by UIComponent.getRenderer().


isValueReference

public static boolean isValueReference(String value)
Return true if the specified string contains an EL expression.

UIComponent properties are often required to be value-binding expressions; this method allows code to check whether that is the case or not.


setPageContext

public void setPageContext(javax.servlet.jsp.PageContext pageContext)
Standard method invoked by the JSP framework to inform this tag of the PageContext associated with the jsp page currently being processed.

Specified by:
setPageContext in interface javax.servlet.jsp.tagext.Tag

getParent

public javax.servlet.jsp.tagext.Tag getParent()
Returns the enclosing JSP tag object. Note that this is not necessarily a JSF tag.

Specified by:
getParent in interface javax.servlet.jsp.tagext.Tag

setParent

public void setParent(javax.servlet.jsp.tagext.Tag parent)
Standard method invoked by the JSP framework to inform this tag of the enclosing JSP tag object.

Specified by:
setParent in interface javax.servlet.jsp.tagext.Tag

doStartTag

public int doStartTag()
               throws javax.servlet.jsp.JspException
Invoked by the standard jsp processing mechanism when the opening tag of a JSF component element is found.

The UIComponent associated with this tag is created (if the view doesn't exist) or located if the view is being re-rendered. If the component is not "suppressed" then its encodeBegin method is called (see method isSuppressed). Note also that method encodeBegin is not called for components for which getRendersChildren returns true; that occurs only in doEndTag.

Specified by:
doStartTag in interface javax.servlet.jsp.tagext.Tag
Throws:
javax.servlet.jsp.JspException

doEndTag

public int doEndTag()
             throws javax.servlet.jsp.JspException
Invoked by the standard jsp processing mechanism when the closing tag of a JSF component element is found.

When the view is being re-rendered, any former children of this tag's corresponding component which do not have corresponding tags as children of this tag are removed from the view. This isn't likely to be a common occurrence: wrapping JSF tags in JSTL tag "c:if" is one possible cause. Programmatically created components are not affected by this.

If the corresponding component returns true from getRendersChildren then its encodeBegin and encodeChildren methods are called here.

The component's encodeEnd method is called provided the component is not "suppressed".

Specified by:
doEndTag in interface javax.servlet.jsp.tagext.Tag
Throws:
javax.servlet.jsp.JspException

encodeBegin

protected void encodeBegin()
                    throws IOException
Invoke encodeBegin on the associated UIComponent. Subclasses can override this method to perform custom processing before or after the UIComponent method invocation.

Throws:
IOException

encodeChildren

protected void encodeChildren()
                       throws IOException
Invoke encodeChildren on the associated UIComponent. Subclasses can override this method to perform custom processing before or after the UIComponent method invocation. This is only invoked for components whose getRendersChildren method returns true.

Throws:
IOException

encodeEnd

protected void encodeEnd()
                  throws IOException
Invoke encodeEnd on the associated UIComponent. Subclasses can override this method to perform custom processing before or after the UIComponent method invocation.

Throws:
IOException

findComponent

protected UIComponent findComponent(FacesContext context)
                             throws javax.servlet.jsp.JspException
Return the corresponding UIComponent for this tag, creating it if necessary.

If this is not the first time this method has been called, then return the cached component instance found last time.

If this is not the first time this view has been seen, then locate the existing component using the id attribute assigned to this tag and return it. Note that this is simple for components with user-assigned ids. For components with generated ids, the "reattachment" relies on the fact that UIViewRoot will generate the same id values for tags in this page as it did when first generating the view. For this reason all JSF tags within a JSTL "c:if" are required to have explicitly-assigned ids.

Otherwise create the component, populate its properties from the xml attributes on this JSP tag and attach it to its parent.

When a component is found or created the parent JSP tag is also told that the component has been "seen". When the parent tag ends it will delete any components which were in the view previously but have not been seen this time; see doEndTag for more details.

Throws:
javax.servlet.jsp.JspException

getDoStartValue

protected int getDoStartValue()
                       throws javax.servlet.jsp.JspException
Get the value to be returned by the doStartTag method to the JSP framework. Subclasses which wish to use the inherited doStartTag but control whether the tag is permitted to contain nested tags or not can just override this method to return Tag.SOME_CONSTANT.

Returns:
Tag.EVAL_BODY_INCLUDE
Throws:
javax.servlet.jsp.JspException

getDoEndValue

protected int getDoEndValue()
                     throws javax.servlet.jsp.JspException
Get the value to be returned by the doEndTag method to the JSP framework. Subclasses which wish to use the inherited doEndTag but control whether the tag is permitted to contain nested tags or not can just override this method to return Tag.SOME_CONSTANT.

Returns:
Tag.EVAL_PAGE
Throws:
javax.servlet.jsp.JspException

getFacesContext

protected FacesContext getFacesContext()

getFacetName

protected String getFacetName()

isSuppressed

protected boolean isSuppressed()
Determine whether this component renders itself. A component is "suppressed" when it is either not rendered, or when it is rendered by its parent component at a time of the parent's choosing.


setProperties

protected void setProperties(UIComponent component)

setupResponseWriter

protected void setupResponseWriter()


Copyright © 2012 The Apache Software Foundation. All Rights Reserved.