Jakarta EE 11.0.0 · jakarta.faces.render.Renderer · APIdia, the JavaDoc alternative

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 jakarta.faces.event.ListenerFor annotation is attached to the class definition of a Renderer, that class must also implement jakarta.faces.event.ComponentSystemEventListener, and the action pertaining to the processing of ResourceDependency on a Renderer described in jakarta.faces.event.ListenerFor must be taken.

If the jakarta.faces.application.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.

The generic parameter T represents the component class.

Field Summary

Modifier and Type	Field and Description
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.

Constructor Summary

Access	Constructor and Description
public	Renderer()

Method Summary

Modifier and Type	Method and Description
public String	Returns: the converted `clientId` convertClientId(FacesContext `FacesContext` for the current request context, String the client identifier to be converted to client a specific format. clientId) Convert the component generated client id to a form suitable for transmission to the client.
public void	decode(FacesContext `FacesContext` for the request we are processing context, T `UIComponent` to be decoded. component) Decode any new state of the specified `UIComponent` from the request contained in the specified `FacesContext`, and store that state on the `UIComponent`.
public void	encodeBegin(FacesContext `FacesContext` for the request we are processing context, T `UIComponent` to be rendered component) Render the beginning specified `UIComponent` to the output stream or writer associated with the response we are creating.
public void	encodeChildren(FacesContext `FacesContext` for the response we are creating context, T `UIComponent` whose children are to be rendered component) Render the child components of this `UIComponent`, following the rules described for `encodeBegin()` to acquire the appropriate value to be rendered.
public void	encodeEnd(FacesContext `FacesContext` for the response we are creating context, T `UIComponent` to be rendered 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.
public Object	Returns: the converted value getConvertedValue(FacesContext `FacesContext` for the request we are processing context, T `UIComponent` to be decoded. component, Object a value stored on the component during `decode`. submittedValue) Attempt to convert previously stored state information into an object of the type required for this component (optionally using the registered `jakarta.faces.convert.Converter` for this component, if there is one).
public boolean	Returns: the current value of the flag getRendersChildren() Return a flag indicating whether this `Renderer` is responsible for rendering the children the component it is asked to render.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Field Detail

PASSTHROUGH_RENDERER_LOCALNAME_KEY back to summary

PASSTHROUGH_RENDERER_LOCALNAME_KEY	back to summary
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. Since 2.2

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.

Since: 2.2

Constructor Detail

Renderer	back to summary
public Renderer()

Method Detail

convertClientId back to summary

convertClientId	back to summary
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. Parameters context:FacesContext `FacesContext` for the current request clientId:String the client identifier to be converted to client a specific format. Returns:String the converted `clientId` Exceptions NullPointerException: if `context` or `clientId` 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.

Parameters

context:FacesContext: FacesContext for the current request
clientId:String: the client identifier to be converted to client a specific format.

Returns:String

the converted clientId

Exceptions

NullPointerException:: if context or clientId is null

decode back to summary

decode	back to summary
public void decode(FacesContext context, T 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`. Parameters context:FacesContext `FacesContext` for the request we are processing component:T `UIComponent` to be decoded. Exceptions NullPointerException: if `context` or `component` is `null`

public void decode(FacesContext context, T 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.

Parameters

context:FacesContext: FacesContext for the request we are processing
component:T: UIComponent to be decoded.

Exceptions

NullPointerException:: if context or component is null

encodeBegin back to summary

encodeBegin	back to summary
public void encodeBegin(FacesContext context, T 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. Parameters context:FacesContext `FacesContext` for the request we are processing component:T `UIComponent` to be rendered Exceptions IOException: if an input/output error occurs while rendering NullPointerException: if `context` or `component` is null

public void encodeBegin(FacesContext context, T 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.

Parameters

context:FacesContext: FacesContext for the request we are processing
component:T: UIComponent to be rendered

Exceptions

IOException:: if an input/output error occurs while rendering
NullPointerException:: if context or component is null

encodeChildren back to summary

encodeChildren	back to summary
public void encodeChildren(FacesContext context, T 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`. Parameters context:FacesContext `FacesContext` for the response we are creating component:T `UIComponent` whose children are to be rendered Exceptions IOException: if an input/output error occurs while rendering NullPointerException: if `context` or `component` is `null`

public void encodeChildren(FacesContext context, T 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.

Parameters

context:FacesContext: FacesContext for the response we are creating
component:T: UIComponent whose children are to be rendered

Exceptions

IOException:: if an input/output error occurs while rendering
NullPointerException:: if context or component is null

encodeEnd back to summary

encodeEnd	back to summary
public void encodeEnd(FacesContext context, T 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. Parameters context:FacesContext `FacesContext` for the response we are creating component:T `UIComponent` to be rendered Exceptions IOException: if an input/output error occurs while rendering NullPointerException: if `context` or `component` is `null`

public void encodeEnd(FacesContext context, T 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.

Parameters

context:FacesContext: FacesContext for the response we are creating
component:T: UIComponent to be rendered

Exceptions

IOException:: if an input/output error occurs while rendering
NullPointerException:: if context or component is null

getConvertedValue back to summary

getConvertedValue	back to summary
public Object getConvertedValue(FacesContext context, T 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 `jakarta.faces.convert.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. Parameters context:FacesContext `FacesContext` for the request we are processing component:T `UIComponent` to be decoded. submittedValue:Object a value stored on the component during `decode`. Returns:Object the converted value Exceptions ConverterException: if the submitted value cannot be converted successfully. NullPointerException: if `context` or `component` is `null`

public Object getConvertedValue(FacesContext context, T 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 jakarta.faces.convert.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.

Parameters

context:FacesContext: FacesContext for the request we are processing
component:T: UIComponent to be decoded.
submittedValue:Object: a value stored on the component during decode.

Returns:Object

the converted value

Exceptions

ConverterException:: if the submitted value cannot be converted successfully.
NullPointerException:: if context or component is null

getRendersChildren back to summary

getRendersChildren	back to summary
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`. Returns:boolean the current value of the flag

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.

Returns:boolean: the current value of the flag

public abstract Class Renderer<T extends UIComponent>

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail