ViewHandler (Apache MyFaces JSF-2.3 Core API 2.3.7 API)

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

Direct Known Subclasses:

ViewHandlerWrapper
```
public abstract class ViewHandler
extends Object
```
A ViewHandler manages the component-tree-creation and component-tree-rendering parts of a request lifecycle (ie "create view", "restore view" and "render response").
A ViewHandler is responsible for generating the component tree when a new view is requested; see method "createView".
When the user performs a "postback", ie activates a UICommand component within a view, then the ViewHandler is responsible for recreating a view tree identical to the one used previously to render that view; see method "restoreView".
And the ViewHandler is also responsible for rendering the final output to be sent to the user by invoking the rendering methods on components; see method "renderView".
This class also isolates callers from the underlying request/response system. In particular, this class does not explicitly depend upon the javax.servlet apis. This allows JSF to be used on servers that do not implement the servlet API (for example, plain CGI).
Examples:
- A JSP ViewHandler exists for using "jsp" pages as the presentation technology. This class then works together with a taghandler class and a jsp servlet class to implement the methods on this abstract class definition.
- A Facelets ViewHandler instead uses an xml file to define the components and non-component data that make up a specific view.
Of course there is no reason why the "template" needs to be a textual file. A view could be generated based on data in a database, or many other mechanisms.
This class is expected to be invoked via the concrete implementation of Lifecycle.
For the official specification for this class, see JSF Specification.

Field Summary

Fields
Modifier and Type	Field and Description
`static String`	`CHARACTER_ENCODING_KEY`
`static String`	`DEFAULT_FACELETS_SUFFIX`
`static String`	`DEFAULT_SUFFIX`
`static String`	`DEFAULT_SUFFIX_PARAM_NAME` Indicate the default suffixes, separated by spaces to derive the default file URI used by JSF to create views and render pages.
`static String`	`DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME`
`static String`	`FACELETS_BUFFER_SIZE_PARAM_NAME` Define the default buffer size value passed to ExternalContext.setResponseBufferResponse() and in a servlet environment to HttpServletResponse.setBufferSize().
`static String`	`FACELETS_DECORATORS_PARAM_NAME` Set of class names, separated by ';', implementing TagDecorator interface, used to transform a view definition in a facelet abstract syntax tree, that is used later to generate a component tree.
`static String`	`FACELETS_LIBRARIES_PARAM_NAME` Set of .taglib.xml files, separated by ';' that should be loaded by facelet engine.
`static String`	`FACELETS_REFRESH_PERIOD_PARAM_NAME` Define the period used to refresh the facelet abstract syntax tree from the view definition file.
`static String`	`FACELETS_SKIP_COMMENTS_PARAM_NAME` Skip comments found on a facelet file.
`static String`	`FACELETS_SUFFIX_PARAM_NAME` The default extension used to handle facelets pages.
`static String`	`FACELETS_VIEW_MAPPINGS_PARAM_NAME` Set of extensions handled by facelets, separated by ';'.

Constructor Summary

Constructors
Constructor and Description

ViewHandler()

Constructors
Constructor and Description
`ViewHandler()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addProtectedView(String urlPattern)`
`String`	`calculateCharacterEncoding(FacesContext context)`
`abstract Locale`	`calculateLocale(FacesContext context)` Return the Locale object that should be used when rendering this view to the current user.
`abstract String`	`calculateRenderKitId(FacesContext context)` Return the id of an available render-kit that should be used to map the JSF components into user presentation.
`abstract UIViewRoot`	`createView(FacesContext context, String viewId)` Build a root node for a component tree.
`String`	`deriveLogicalViewId(FacesContext context, String rawViewId)`
`String`	`deriveViewId(FacesContext context, String input)`
`abstract String`	`getActionURL(FacesContext context, String viewId)` Returns a URL, suitable for encoding and rendering, that (if activated) will cause the JSF request processing lifecycle for the specified viewId to be executed
`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.
`Set<String>`	`getProtectedViewsUnmodifiable()`
`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)` Returns a URL, suitable for encoding and rendering, that (if activated) will retrieve the specified web application resource.
`ViewDeclarationLanguage`	`getViewDeclarationLanguage(FacesContext context, String viewId)` Return the ViewDeclarationLanguage instance used for this ViewHandler instance.
`Stream<String>`	`getViews(FacesContext facesContext, String path, int maxDepth, ViewVisitOption... options)`
`Stream<String>`	`getViews(FacesContext facesContext, String path, ViewVisitOption... options)`
`abstract String`	`getWebsocketURL(FacesContext context, String channelAndToken)` Return a JSF URL that represents a websocket connection for the passed channel and channelToken
`void`	`initView(FacesContext context)` Initialize the view for the request processing lifecycle.
`boolean`	`removeProtectedView(String urlPattern)`
`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
```
    See Also:
    
    Constant Field Values
  - DEFAULT_FACELETS_SUFFIX
```
public static final String DEFAULT_FACELETS_SUFFIX
```
    See Also:
    
    Constant Field Values
  - DEFAULT_SUFFIX
```
public static final String DEFAULT_SUFFIX
```
    See Also:
    
    Constant Field Values
  - DEFAULT_SUFFIX_PARAM_NAME
```
@JSFWebConfigParam(defaultValue=".xhtml .view.xml .jsp",
                   since="1.1",
                   group="viewhandler")
public static final String DEFAULT_SUFFIX_PARAM_NAME
```
    Indicate the default suffixes, separated by spaces to derive the default file URI used by JSF to create views and render pages.
    
    See Also:
    
    Constant Field Values
  - FACELETS_SUFFIX_PARAM_NAME
```
@JSFWebConfigParam(defaultValue=".xhtml",
                   since="2.0",
                   group="viewhandler")
public static final String FACELETS_SUFFIX_PARAM_NAME
```
    The default extension used to handle facelets pages.
    
    See Also:
    
    Constant Field Values
  - FACELETS_VIEW_MAPPINGS_PARAM_NAME
```
@JSFWebConfigParam(since="2.0",
                   group="viewhandler")
public static final String FACELETS_VIEW_MAPPINGS_PARAM_NAME
```
    Set of extensions handled by facelets, separated by ';'.
    
    See Also:
    
    Constant Field Values
  - DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME
```
@JSFWebConfigParam(since="2.2")
public static final String DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME
```
    See Also:
    
    Constant Field Values
  - FACELETS_BUFFER_SIZE_PARAM_NAME
```
@JSFWebConfigParam(since="2.0",
                   alias="facelets.BUFFER_SIZE",
                   classType="java.lang.Integer",
                   tags="performance",
                   defaultValue="1024",
                   desc="Define the default buffer size value passed to ExternalContext.setResponseBufferResponse() and in a servlet environment to HttpServletResponse.setBufferSize()")
public static final String FACELETS_BUFFER_SIZE_PARAM_NAME
```
    Define the default buffer size value passed to ExternalContext.setResponseBufferResponse() and in a servlet environment to HttpServletResponse.setBufferSize().
    
    See Also:
    
    Constant Field Values
  - FACELETS_DECORATORS_PARAM_NAME
```
@JSFWebConfigParam(since="2.0",
                   alias="facelets.DECORATORS")
public static final String FACELETS_DECORATORS_PARAM_NAME
```
    Set of class names, separated by ';', implementing TagDecorator interface, used to transform a view definition in a facelet abstract syntax tree, that is used later to generate a component tree.
    
    See Also:
    
    Constant Field Values
  - FACELETS_LIBRARIES_PARAM_NAME
```
@JSFWebConfigParam(since="2.0",
                   desc="Set of .taglib.xml files, separated by \';\' that should be loaded by facelet engine.",
                   alias="facelets.LIBRARIES")
public static final String FACELETS_LIBRARIES_PARAM_NAME
```
    Set of .taglib.xml files, separated by ';' that should be loaded by facelet engine.
    
    See Also:
    
    Constant Field Values
  - FACELETS_REFRESH_PERIOD_PARAM_NAME
```
@JSFWebConfigParam(since="2.0",
                   defaultValue="-1",
                   alias="facelets.REFRESH_PERIOD",
                   classType="java.lang.Long",
                   tags="performance")
public static final String FACELETS_REFRESH_PERIOD_PARAM_NAME
```
    Define the period used to refresh the facelet abstract syntax tree from the view definition file.
    By default is infinite (no active).
    
    See Also:
    
    Constant Field Values
  - FACELETS_SKIP_COMMENTS_PARAM_NAME
```
@JSFWebConfigParam(since="2.0",
                   alias="facelets.SKIP_COMMENTS")
public static final String FACELETS_SKIP_COMMENTS_PARAM_NAME
```
    Skip comments found on a facelet file.
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - ViewHandler
```
public ViewHandler()
```
- Method Detail
  - calculateCharacterEncoding
```
public String calculateCharacterEncoding(FacesContext context)
```
    Since:
    
    JSF 1.2
  - calculateLocale
```
public abstract Locale calculateLocale(FacesContext context)
```
    Return the Locale object that should be used when rendering this view to the current user.
    Some request protocols allow an application user to specify what locale they prefer the response to be in. For example, HTTP requests can specify the "accept-language" header.
    Method Application.getSupportedLocales() defines what locales this JSF application is capable of supporting.
    This method should match such sources of data up and return the Locale object that is the best choice for rendering the current application to the current user.
  - calculateRenderKitId
```
public abstract String calculateRenderKitId(FacesContext context)
```
    Return the id of an available render-kit that should be used to map the JSF components into user presentation.
    The render-kit selected (eg html, xhtml, pdf, xul, ...) may depend upon the user, properties associated with the request, etc.
  - createView
```
public abstract UIViewRoot createView(FacesContext context,
                                      String viewId)
```
    Build a root node for a component tree.
    When a request is received, this method is called if restoreView returns null, ie this is not a "postback". In this case, a root node is created and then renderView is invoked. It is the responsibility of the renderView method to build the full component tree (ie populate the UIViewRoot with descendant nodes).
    This method is also invoked when navigation occurs from one view to another, where the viewId passed is the id of the new view to be displayed. Again it is the responsibility of renderView to then populate the viewroot with descendants.
    The locale and renderKit settings are inherited from the current UIViewRoot that is configured before this method is called. That means of course that they do NOT get set for GET requests, including navigation that has the redirect flag set.
  - deriveViewId
```
public String deriveViewId(FacesContext context,
                           String input)
```
    Parameters:
    
    context -
    
    input -
    
    Returns:
    
    Since:
    
    2.0
  - deriveLogicalViewId
```
public String deriveLogicalViewId(FacesContext context,
                                  String rawViewId)
```
    Parameters:
    
    context -
    
    rawViewId -
    
    Returns:
    
    Since:
    
    2.1
  - getActionURL
```
public abstract String getActionURL(FacesContext context,
                                    String viewId)
```
    Returns a URL, suitable for encoding and rendering, that (if activated) will cause the JSF request processing lifecycle for the specified viewId to be executed
  - 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 -
    
    viewId -
    
    parameters -
    
    includeViewParams -
    
    Returns:
    
    Since:
    
    2.0
  - getViewDeclarationLanguage
```
public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context,
                                                          String viewId)
```
    Return the ViewDeclarationLanguage instance used for this ViewHandler instance.
    The default implementation of this method returns null.
    
    Parameters:
    
    context -
    
    viewId -
    
    Returns:
    
    Since:
    
    2.0
  - 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 -
    
    viewId -
    
    parameters -
    
    includeViewParams -
    
    Returns:
    
    Since:
    
    2.0
  - getResourceURL
```
public abstract String getResourceURL(FacesContext context,
                                      String path)
```
    Returns a URL, suitable for encoding and rendering, that (if activated) will retrieve the specified web application resource.
  - 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
    
    Since:
    
    JSF 1.2
  - 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.
    
    Throws:
    
    IOException
    
    FacesException
  - 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.
  - 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).
    
    Throws:
    
    IOException
  - addProtectedView
```
public void addProtectedView(String urlPattern)
```
    Parameters:
    
    urlPattern -
    
    Since:
    
    2.2
  - removeProtectedView
```
public boolean removeProtectedView(String urlPattern)
```
    Parameters:
    
    urlPattern -
    
    Since:
    
    2.2
  - getProtectedViewsUnmodifiable
```
public Set<String> getProtectedViewsUnmodifiable()
```
    Returns:
    
    Since:
    
    2.2
  - getWebsocketURL
```
public abstract String getWebsocketURL(FacesContext context,
                                       String channelAndToken)
```
    Return a JSF URL that represents a websocket connection for the passed channel and channelToken
    
    Parameters:
    
    context -
    
    channelAndToken -
    
    Returns:
    
    Since:
    
    2.3
  - getViews
```
public Stream<String> getViews(FacesContext facesContext,
                               String path,
                               ViewVisitOption... options)
```
    Parameters:
    
    facesContext -
    
    path -
    
    options -
    
    Returns:
    
    Since:
    
    2.3
  - getViews
```
public Stream<String> getViews(FacesContext facesContext,
                               String path,
                               int maxDepth,
                               ViewVisitOption... options)
```
    Parameters:
    
    facesContext -
    
    path -
    
    maxDepth -
    
    options -
    
    Returns:
    
    Since:
    
    2.3

Class ViewHandler

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

CHARACTER_ENCODING_KEY

DEFAULT_FACELETS_SUFFIX

DEFAULT_SUFFIX

DEFAULT_SUFFIX_PARAM_NAME

FACELETS_SUFFIX_PARAM_NAME

FACELETS_VIEW_MAPPINGS_PARAM_NAME

DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME

FACELETS_BUFFER_SIZE_PARAM_NAME

FACELETS_DECORATORS_PARAM_NAME

FACELETS_LIBRARIES_PARAM_NAME

FACELETS_REFRESH_PERIOD_PARAM_NAME

FACELETS_SKIP_COMMENTS_PARAM_NAME

Constructor Detail

ViewHandler

Method Detail

calculateCharacterEncoding

calculateLocale

calculateRenderKitId

createView

deriveViewId

deriveLogicalViewId

getActionURL

getBookmarkableURL

getViewDeclarationLanguage

getRedirectURL

getResourceURL

initView

renderView

restoreView

writeState

addProtectedView

removeProtectedView

getProtectedViewsUnmodifiable

getWebsocketURL

getViews

getViews