javax.faces.render

## Class Renderer

- java.lang.Object
- - javax.faces.render.Renderer

- Direct Known Subclasses:
    RendererWrapper

      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.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static 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

    Constructors
    Constructor and Description
    `Renderer()`

  - ### Method Summary

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

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PASSTHROUGH_RENDERER_LOCALNAME_KEY

          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
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Renderer

          public Renderer()

  - ### Method Detail

    - #### decode

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

      Parameters:
        `context` - `FacesContext` for the request we are processing
        `component` - `UIComponent` to be decoded.
      Throws:
        `NullPointerException` - if `context` or `component` is `null`

    - #### encodeBegin

          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.

      Parameters:
        `context` - `FacesContext` for the request we are processing
        `component` - `UIComponent` to be rendered
      Throws:
        `IOException` - if an input/output error occurs while rendering
        `NullPointerException` - if `context` or `component` is null

    - #### encodeChildren

          public 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`.

      Parameters:
        `context` - `FacesContext` for the response we are creating
        `component` - `UIComponent` whose children are to be rendered
      Throws:
        `IOException` - if an input/output error occurs while rendering
        `NullPointerException` - if `context` or `component` is `null`

    - #### encodeEnd

          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.

      Parameters:
        `context` - `FacesContext` for the response we are creating
        `component` - `UIComponent` to be rendered
      Throws:
        `IOException` - if an input/output error occurs while rendering
        `NullPointerException` - if `context` or `component` is `null`

    - #### convertClientId

          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` for the current request
        `clientId` - the client identifier to be converted to client a specific format.
      Throws:
        `NullPointerException` - if `context` or `clientId` is `null`

    - #### getRendersChildren

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

    - #### getConvertedValue

          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.

      Parameters:
        `context` - `FacesContext` for the request we are processing
        `component` - `UIComponent` to be decoded.
        `submittedValue` - a value stored on the component during `decode`.
      Throws:
        `ConverterException` - if the submitted value cannot be converted successfully.
        `NullPointerException` - if `context` or `component` is `null`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.