public abstract class Renderer extends Object
A Renderer converts the internal representation of
UIComponent
s 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 Renderer
s are packaged as a RenderKit
, and together support the rendering of all of the
UIComponent
s in a view associated with a FacesContext
. Within the set of Renderer
s 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 String |
PASSTHROUGH_RENDERER_LOCALNAME_KEY
The key in the component passthrough attributes |
Constructor and Description |
---|
Renderer() |
Modifier and Type | Method and Description |
---|---|
String |
convertClientId(FacesContext context,
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. |
Object |
getConvertedValue(FacesContext context,
UIComponent component,
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 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.NullPointerException
- if context
or component
is null
public void encodeBegin(FacesContext context, UIComponent component) throws 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 renderedIOException
- if an input/output error occurs while renderingNullPointerException
- if context
or component
is nullpublic void encodeChildren(FacesContext context, UIComponent component) throws 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 renderedIOException
- if an input/output error occurs while renderingNullPointerException
- if context
or component
is null
public void encodeEnd(FacesContext context, UIComponent component) throws 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 renderedIOException
- if an input/output error occurs while renderingNullPointerException
- if context
or component
is null
public String convertClientId(FacesContext context, 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.clientId
NullPointerException
- if context
or clientId
is null
public 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 Object getConvertedValue(FacesContext context, UIComponent component, 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.NullPointerException
- if context
or component
is null
Copyright © 2018,2020 Eclipse Foundation.
Use is subject to license terms.