public abstract class Renderer
extends java.lang.Object
A Renderer converts
the internal representation of UIComponents into the output
stream (or writer) associated with the response we are creating for a
particular request. Each Renderer knows how to render
one or more UIComponent types (or classes), and advertises a
set of render-dependent attributes that it recognizes for each
supported UIComponent.
Families of Renderers are packaged as a RenderKit,
and together support the rendering of all of the UIComponents
in a view associated with a FacesContext. Within the set of
Renderers for a particular RenderKit, each must be
uniquely identified by the rendererType property.
Individual Renderer instances will be instantiated as requested
during the rendering process, and will remain in existence for the
remainder of the lifetime of a web application. Because each instance
may be invoked from more than one request processing thread simultaneously,
they MUST be programmed in a thread-safe manner.
If the ListenerFor annotation is
attached to the class definition of a Renderer, that
class must also implement ComponentSystemEventListener, and the action
pertaining to the processing of ResourceDependency on a
Renderer described in ListenerFor must be taken.
If the ResourceDependency
annotation is attached to the class definition of a
Renderer, the action pertaining to the processing of
ResourceDependency on a Renderer described
in UIComponent.getChildren() must be taken.
| Modifier and Type | Field and Description |
|---|---|
static java.lang.String |
PASSTHROUGH_RENDERER_LOCALNAME_KEY
The key in the component passthrough
attributes |
| Constructor and Description |
|---|
Renderer() |
| Modifier and Type | Method and Description |
|---|---|
java.lang.String |
convertClientId(FacesContext context,
java.lang.String clientId)
Convert the component generated client id to a form suitable
for transmission to the client.
|
void |
decode(FacesContext context,
UIComponent component)
Decode any new state of the specified
UIComponent
from the request contained in the specified FacesContext,
and store that state on the UIComponent. |
void |
encodeBegin(FacesContext context,
UIComponent component)
Render the beginning specified
UIComponent to the
output stream or writer associated with the response we are creating. |
void |
encodeChildren(FacesContext context,
UIComponent component)
Render the child components of this
UIComponent, following
the rules described for encodeBegin() to acquire the
appropriate value to be rendered. |
void |
encodeEnd(FacesContext context,
UIComponent component)
Render the ending of the current state of the specified
UIComponent, following the rules described for
encodeBegin() to acquire the appropriate value
to be rendered. |
java.lang.Object |
getConvertedValue(FacesContext context,
UIComponent component,
java.lang.Object submittedValue)
Attempt to convert previously stored state information into an
object of the type required for this component (optionally using the
registered
Converter for this component,
if there is one). |
boolean |
getRendersChildren()
Return a flag indicating whether this
Renderer is responsible
for rendering the children the component it is asked to render. |
public static final java.lang.String PASSTHROUGH_RENDERER_LOCALNAME_KEY
The key in the component passthrough
attributes Map for the localName of the element corresponding to the component.
public void decode(FacesContext context, UIComponent component)
Decode any new state of the specified UIComponent
from the request contained in the specified FacesContext,
and store that state on the UIComponent.
During decoding, events may be enqueued for later processing
(by event listeners that have registered an interest), by calling
queueEvent() on the associated UIComponent.
context - FacesContext for the request we are processingcomponent - UIComponent to be decoded.java.lang.NullPointerException - if context
or component is nullpublic void encodeBegin(FacesContext context, UIComponent component) throws java.io.IOException
Render the beginning specified UIComponent to the
output stream or writer associated with the response we are creating.
If the conversion attempted in a previous call to
getConvertedValue() for this component failed, the state
information saved during execution
of decode() should be used to reproduce the incorrect
input.
context - FacesContext for the request we are processingcomponent - UIComponent to be renderedjava.io.IOException - if an input/output error occurs while renderingjava.lang.NullPointerException - if context
or component is nullpublic void encodeChildren(FacesContext context, UIComponent component) throws java.io.IOException
Render the child components of this UIComponent, following
the rules described for encodeBegin() to acquire the
appropriate value to be rendered. This method will only be called
if the rendersChildren property of this component
is true.
context - FacesContext for the response we are creatingcomponent - UIComponent whose children are to be renderedjava.io.IOException - if an input/output error occurs while renderingjava.lang.NullPointerException - if context
or component is nullpublic void encodeEnd(FacesContext context, UIComponent component) throws java.io.IOException
Render the ending of the current state of the specified
UIComponent, following the rules described for
encodeBegin() to acquire the appropriate value
to be rendered.
context - FacesContext for the response we are creatingcomponent - UIComponent to be renderedjava.io.IOException - if an input/output error occurs while renderingjava.lang.NullPointerException - if context
or component is nullpublic java.lang.String convertClientId(FacesContext context, java.lang.String clientId)
Convert the component generated client id to a form suitable for transmission to the client.
The default implementation returns the argument
clientId unchanged.
context - FacesContext for the current requestclientId - the client identifier to be converted to client a
specific format.clientIdjava.lang.NullPointerException - if context
or clientId is nullpublic boolean getRendersChildren()
Return a flag indicating whether this Renderer is responsible
for rendering the children the component it is asked to render.
The default implementation returns false.
public java.lang.Object getConvertedValue(FacesContext context, UIComponent component, java.lang.Object submittedValue) throws ConverterException
Attempt to convert previously stored state information into an
object of the type required for this component (optionally using the
registered Converter for this component,
if there is one). If conversion is successful, the new value
should be returned from this method; if not, a
ConverterException should be thrown.
context - FacesContext for the request we are processingcomponent - UIComponent to be decoded.submittedValue - a value stored on the component during
decode.ConverterException - if the submitted value
cannot be converted successfully.java.lang.NullPointerException - if context
or component is null