Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## javax.faces.application
Class ViewHandler

    java.lang.Object
      javax.faces.application.ViewHandler

Direct Known Subclasses:
  ViewHandlerWrapper

    public abstract class ViewHandler

extends Object

ViewHandler is the pluggablity mechanism for allowing implementations of or applications using the JavaServer Faces specification to provide their own handling of the activities in the Render Response and Restore View phases of the request processing lifecycle. This allows for implementations to support different response generation technologies, as well as alternative strategies for saving and restoring the state of each view. An implementation of this class must be thread-safe.

Please see `StateManager` for information on how the `ViewHandler` interacts the `StateManager`.

Version 2 of the specification formally introduced the concept of View Declaration Language. A View Declaration Language (VDL) is a syntax used to declare user interfaces comprised of instances of JSF `UIComponent`s. Any of the responsibilities of the `ViewHandler` that specifically deal with the VDL sub-system are now the domain of the VDL implementation. These responsibilities are defined on the `ViewDeclarationLanguage` class. The `ViewHandler` provides `getViewDeclarationLanguage(javax.faces.context.FacesContext, java.lang.String)` as a convenience method to access the VDL implementation given a `viewId`.

Field Summary
`static String` | `CHARACTER_ENCODING_KEY` The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.
`static String` | `DEFAULT_FACELETS_SUFFIX` The value to use for the default extension for Facelet based XHTML pages if the webapp is using url extension mapping.
`static String` | `DEFAULT_SUFFIX` The value to use for the default extension if the webapp is using url extension mapping.
`static String` | `DEFAULT_SUFFIX_PARAM_NAME` Allow the web application to define a list of alternate suffixes for pages containing JSF content.
`static String` | `FACELETS_SUFFIX_PARAM_NAME` Allow the web application to define an alternate suffix for Facelet based XHTML pages containing JSF content.
`static String` | `FACELETS_VIEW_MAPPINGS_PARAM_NAME` Allow the web application to define a semicolon (;) separated list of strings that is used to forcibly declare that certain pages in the application must be interpreted as using Facelets, regardless of their extension.

Constructor Summary
`ViewHandler()`

Method Summary
`String` | `calculateCharacterEncoding(FacesContext context)` Returns the correct character encoding to be used for this request.
`abstract Locale` | `calculateLocale(FacesContext context)` Returns an appropriate `Locale` to use for this and subsequent requests for the current client.
`abstract String` | `calculateRenderKitId(FacesContext context)` Return an appropriate `renderKitId` for this and subsequent requests from the current client.
`abstract UIViewRoot` | `createView(FacesContext context, String viewId)` Create and return a new `UIViewRoot` instance initialized with information from the argument `FacesContext` and `viewId`.
`String` | `deriveViewId(FacesContext context, String rawViewId)` Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.5.2.
`abstract String` | `getActionURL(FacesContext context, String viewId)` If the value returned from this method is used as the `file` argument to the four-argument constructor for `java.net.URL` (assuming appropriate values are used for the first three arguments), then a client making a request to the `toExternalForm()` of that `URL` will select the argument `viewId` for traversing the JSF lifecycle.
`String` | `getBookmarkableURL(FacesContext context, String viewId, Map<String,List<String>> parameters, boolean includeViewParams)` Return a JSF action URL derived from the viewId argument that is suitable to be used as the target of a link in a JSF response.
`String` | `getRedirectURL(FacesContext context, String viewId, Map<String,List<String>> parameters, boolean includeViewParams)` Return a JSF action URL derived from the `viewId` argument that is suitable to be used by the `NavigationHandler` to issue a redirect request to the URL using a NonFaces request.
`abstract String` | `getResourceURL(FacesContext context, String path)` If the value returned from this method is used as the `file` argument to the four-argument constructor for `java.net.URL` (assuming appropriate values are used for the first three arguments), then a client making a request to the `toExternalForm()` of that `URL` will select the argument `path` for direct rendering.
`ViewDeclarationLanguage` | `getViewDeclarationLanguage(FacesContext context, String viewId)` Return the `ViewDeclarationLanguage` instance used for this `ViewHandler` instance.
`void` | `initView(FacesContext context)` Initialize the view for the request processing lifecycle.
`abstract void` | `renderView(FacesContext context, UIViewRoot viewToRender)` Perform whatever actions are required to render the response view to the response object associated with the current `FacesContext`.
`abstract UIViewRoot` | `restoreView(FacesContext context, String viewId)` Perform whatever actions are required to restore the view associated with the specified `FacesContext` and `viewId`.
`abstract void` | `writeState(FacesContext context)` Take any appropriate action to either immediately write out the current state information (by calling `StateManager.writeState(javax.faces.context.FacesContext, java.lang.Object)`, or noting where state information should later be written.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### CHARACTER_ENCODING_KEY

    public static final String CHARACTER_ENCODING_KEY

  The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.

  See Also:
    Constant Field Values

### DEFAULT_SUFFIX_PARAM_NAME

    public static final String DEFAULT_SUFFIX_PARAM_NAME

  Allow the web application to define a list of alternate suffixes for pages containing JSF content. This list is a space separated list of values of the form `.<extension>`. The first physical resource whose extension matches one of the configured extensions will be the suffix used to create the view ID. If this init parameter is not specified, the default value is taken from the value of the constant `DEFAULT_SUFFIX`.

  See Also:
    Constant Field Values

### DEFAULT_SUFFIX

    public static final String DEFAULT_SUFFIX

  The value to use for the default extension if the webapp is using url extension mapping.

  See Also:
    Constant Field Values

### FACELETS_SUFFIX_PARAM_NAME

    public static final String FACELETS_SUFFIX_PARAM_NAME

  Allow the web application to define an alternate suffix for Facelet based XHTML pages containing JSF content. If this init parameter is not specified, the default value is taken from the value of the constant `DEFAULT_FACELETS_SUFFIX`

  Since:
    2.0
  See Also:
    Constant Field Values

### DEFAULT_FACELETS_SUFFIX

    public static final String DEFAULT_FACELETS_SUFFIX

  The value to use for the default extension for Facelet based XHTML pages if the webapp is using url extension mapping.

  Since:
    2.0
  See Also:
    Constant Field Values

### FACELETS_VIEW_MAPPINGS_PARAM_NAME

    public static final String FACELETS_VIEW_MAPPINGS_PARAM_NAME

  Allow the web application to define a semicolon (;) separated list of strings that is used to forcibly declare that certain pages in the application must be interpreted as using Facelets, regardless of their extension. Each entry in the semicolon (;) separated list of strings is either a file extension, as in `*.xhtml`, or a resource prefix (starting with '/' and interpreted as relative to the web application root), as in `/user/*`. The latter class of entry can also take the form of `/<filename>.<extension>*` such as `/login.jsp*`. The runtime must also consider the `facelets.VIEW_MAPPINGS` param name as an alias to this param name for backwards compatibility with existing Facelets applications.

  Since:
    2.0
  See Also:
    Constant Field Values

Constructor Detail

### ViewHandler

    public ViewHandler()

Method Detail

### calculateLocale

    public abstract Locale calculateLocale(FacesContext context)

  Returns an appropriate `Locale` to use for this and subsequent requests for the current client.

  Parameters:
    `context` - `FacesContext` for the current request
  Throws:
    `NullPointerException` - if `context` is `null`

### calculateCharacterEncoding

    public String calculateCharacterEncoding(FacesContext context)

  Returns the correct character encoding to be used for this request.

  The following algorithm is employed.

  - Examine the `Content-Type` request header. If it has a `charset` parameter, extract it and return that as the encoding.

  - If no `charset` parameter was found, check for the existence of a session by calling `ExternalContext.getSession(boolean)` passing `false` as the argument. If that method returns `true`, get the session Map by calling `ExternalContext.getSessionMap()` and look for a value under the key given by the value of the symbolic constant `CHARACTER_ENCODING_KEY`. If present, return the value, converted to String.

  - Otherwise, return `null`

  Since:
    1.2

### calculateRenderKitId

    public abstract String calculateRenderKitId(FacesContext context)

  Return an appropriate `renderKitId` for this and subsequent requests from the current client. It is an error for this method to return `null`.

  The default return value is `RenderKitFactory.HTML_BASIC_RENDER_KIT`.

  Parameters:
    `context` - `FacesContext` for the current request
  Throws:
    `NullPointerException` - if `context` is `null`

### createView

    public abstract UIViewRoot createView(FacesContext context,
                                          String viewId)

  Create and return a new `UIViewRoot` instance initialized with information from the argument `FacesContext` and `viewId`. Locate the `ViewDeclarationLanguage` implementation for the VDL used in the view. The argument `viewId` must be converted to a physical `viewId` that can refer to an actual resource suitable for use by the `ViewDeclarationLanguage` `ViewDeclarationLanguage.createView(javax.faces.context.FacesContext, java.lang.String)`, which must be called by this method.

  Throws:
    `NullPointerException` - if `context` is `null`

### deriveViewId

    public String deriveViewId(FacesContext context,
                               String rawViewId)

  Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.5.2.

  The default implementation of this method simply returns rawViewId unchanged.

  Parameters:
    `context` - the `FacesContext` for this request
    `rawViewId` - the `viewId` to derive,
  Since:
    2.0

### getActionURL

    public abstract String getActionURL(FacesContext context,
                                        String viewId)

  If the value returned from this method is used as the `file` argument to the four-argument constructor for `java.net.URL` (assuming appropriate values are used for the first three arguments), then a client making a request to the `toExternalForm()` of that `URL` will select the argument `viewId` for traversing the JSF lifecycle. Please see section JSF.7.5.2 for the complete specification.

  Parameters:
    `context` - `FacesContext` for this request
    `viewId` - View identifier of the desired view
  Throws:
    `IllegalArgumentException` - if `viewId` is not valid for this `ViewHandler`, or does not start with "/".
    `NullPointerException` - if `context` or `viewId` is `null`.

### getResourceURL

    public abstract String getResourceURL(FacesContext context,
                                          String path)

  If the value returned from this method is used as the `file` argument to the four-argument constructor for `java.net.URL` (assuming appropriate values are used for the first three arguments), then a client making a request to the `toExternalForm()` of that `URL` will select the argument `path` for direct rendering. If the specified path starts with a slash, it must be treated as context relative; otherwise, it must be treated as relative to the action URL of the current view.

  Parameters:
    `context` - `FacesContext` for the current request
    `path` - Resource path to convert to a URL
  Throws:
    `IllegalArgumentException` - if `viewId` is not valid for this `ViewHandler`.
    `NullPointerException` - if `context` or `path` is `null`.

### getRedirectURL

    public String getRedirectURL(FacesContext context,
                                 String viewId,
                                 Map<String,List<String>> parameters,
                                 boolean includeViewParams)

  Return a JSF action URL derived from the `viewId` argument that is suitable to be used by the `NavigationHandler` to issue a redirect request to the URL using a NonFaces request. Compiliant implementations must implement this method as specified in section JSF.7.5.2. The default implementation simply calls through to `getActionURL(javax.faces.context.FacesContext, java.lang.String)`, passing the arguments `context` and `viewId`.

  Parameters:
    `context` - The FacesContext processing this request
    `viewId` - The view identifier of the target page
    `parameters` - A mapping of parameter names to one or more values
    `includeViewParams` - A flag indicating whether view parameters should be encoded into this URL
  Since:
    2.0

### getBookmarkableURL

    public String getBookmarkableURL(FacesContext context,
                                     String viewId,
                                     Map<String,List<String>> parameters,
                                     boolean includeViewParams)

  Return a JSF action URL derived from the viewId argument that is suitable to be used as the target of a link in a JSF response. Compiliant implementations must implement this method as specified in section JSF.7.5.2. The default implementation simply calls through to `getActionURL(javax.faces.context.FacesContext, java.lang.String)`, passing the arguments `context` and `viewId`.

  Parameters:
    `context` - The FacesContext processing this request
    `viewId` - The view identifier of the target page
    `parameters` - A mapping of parameter names to one or more values
    `includeViewParams` - A flag indicating whether view parameters should be encoded into this URL
  Since:
    2.0

### getViewDeclarationLanguage

    public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context,
                                                              String viewId)

  Return the `ViewDeclarationLanguage` instance used for this `ViewHandler` instance.

  The default implementation must use `ViewDeclarationLanguageFactory.getViewDeclarationLanguage(java.lang.String)` to obtain the appropriate `ViewDeclarationLanguage` implementation for the argument `viewId`. Any exceptions thrown as a result of invoking that method must not be swallowed.

  The default implementation of this method returns null.

  Since:
    2.0

### initView

    public void initView(FacesContext context)
                  throws FacesException

  Initialize the view for the request processing lifecycle.

  This method must be called at the beginning of the Restore View Phase of the Request Processing Lifecycle. It is responsible for performing any per-request initialization necessary to the operation of the lifycecle.

  The default implementation must perform the following actions. If `ExternalContext.getRequestCharacterEncoding()` returns `null`, call `calculateCharacterEncoding(javax.faces.context.FacesContext)` and pass the result, if non-`null`, into the `ExternalContext.setRequestCharacterEncoding(java.lang.String)` method. If `ExternalContext.getRequestCharacterEncoding()` returns non-`null` take no action.

  Throws:
    `FacesException` - if a problem occurs setting the encoding, such as the `UnsupportedEncodingException` thrown by the underlying Servlet or Portlet technology when the encoding is not supported.

### renderView

    public abstract void renderView(FacesContext context,
                                    UIViewRoot viewToRender)
                             throws IOException,
                                    FacesException

  Perform whatever actions are required to render the response view to the response object associated with the current `FacesContext`.

  Otherwise, the default implementation must obtain a reference to the `ViewDeclarationLanguage` for the `viewId` of the argument `viewToRender` and call its `ViewDeclarationLanguage.renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot)` method, returning the result and not swallowing any exceptions thrown by that method.

  Parameters:
    `context` - `FacesContext` for the current request
    `viewToRender` - the view to render
  Throws:
    `IOException` - if an input/output error occurs
    `NullPointerException` - if `context` or `viewToRender` is `null`
    `FacesException` - if a servlet error occurs

### restoreView

    public abstract UIViewRoot restoreView(FacesContext context,
                                           String viewId)

  Perform whatever actions are required to restore the view associated with the specified `FacesContext` and `viewId`. It may delegate to the `restoreView` of the associated `StateManager` to do the actual work of restoring the view. If there is no available state for the specified `viewId`, return `null`.

  Otherwise, the default implementation must obtain a reference to the `ViewDeclarationLanguage` for this `viewId` and call its `ViewDeclarationLanguage.restoreView(javax.faces.context.FacesContext, java.lang.String)` method, returning the result and not swallowing any exceptions thrown by that method.

  Parameters:
    `context` - `FacesContext` for the current request
    `viewId` - the view identifier for the current request
  Throws:
    `NullPointerException` - if `context` is `null`
    `FacesException` - if a servlet error occurs

### writeState

    public abstract void writeState(FacesContext context)
                             throws IOException

  Take any appropriate action to either immediately write out the current state information (by calling `StateManager.writeState(javax.faces.context.FacesContext, java.lang.Object)`, or noting where state information should later be written.

  This method must do nothing if the current request is an `Ajax` request. When responding to `Ajax` requests, the state is obtained by calling `StateManager.getViewState(javax.faces.context.FacesContext)` and then written into the `Ajax` response during final encoding (`UIViewRoot.encodeEnd(javax.faces.context.FacesContext)`.

  Parameters:
    `context` - `FacesContext` for the current request
  Throws:
    `IOException` - if an input/output error occurs
    `NullPointerException` - if `context` is `null`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2002-2009 Sun Microsystems, Inc. All Rights Reserved.