MultiViewHandler (Jakarta Server Fages API documentation)

java.lang.Object
- javax.faces.application.ViewHandler
- - com.sun.faces.application.view.MultiViewHandler

```
public class MultiViewHandler
extends ViewHandler
```
This ViewHandler implementation handles both JSP-based and Facelets/PDL-based views.

Field Summary
- Fields inherited from class javax.faces.application.ViewHandler
  CHARACTER_ENCODING_KEY, DEFAULT_FACELETS_SUFFIX, DEFAULT_SUFFIX, DEFAULT_SUFFIX_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, FACELETS_SUFFIX_PARAM_NAME, FACELETS_VIEW_MAPPINGS_PARAM_NAME

Constructor Summary

Constructors
Constructor and Description

MultiViewHandler()

Constructors
Constructor and Description
`MultiViewHandler()`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addProtectedView(String urlPattern)` Add the argument `urlPattern` to the thread safe `Set` of protected views for this application.
`protected void`	`addViewParameters(FacesContext ctx, String viewId, Map<String,List<String>> existingParameters)`
`Locale`	`calculateLocale(FacesContext context)` This code is currently common to all `ViewHandlingStrategy` instances.
`String`	`calculateRenderKitId(FacesContext context)` This code is currently common to all `ViewHandlingStrategy` instances.
`protected String`	`convertViewId(FacesContext context, String viewId)` Adjust the viewID per the requirements of `renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot)`.
`UIViewRoot`	`createView(FacesContext context, String viewId)` Derive the physical view ID (i.e.
`String`	`deriveLogicalViewId(FacesContext context, String requestViewId)` Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2.
`protected String`	`derivePhysicalViewId(FacesContext ctx, String requestViewId, boolean checkPhysical)`
`String`	`deriveViewId(FacesContext context, String requestViewId)` Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2.
`protected Locale`	`findMatch(FacesContext context, Locale pref)` Attempts to find a matching locale based on `pref` and list of supported locales, using the matching algorithm as described in JSTL 8.3.2.
`String`	`getActionURL(FacesContext context, String viewId)` This code is currently common to all `ViewHandlingStrategy` instances.
`String`	`getBookmarkableURL(FacesContext context, String viewId, Map<String,List<String>> parameters, boolean includeViewParams)` Return a Jakarta Server Faces action URL derived from the viewId argument that is suitable to be used as the target of a link in a Jakarta Server Faces response.
`protected Map<String,List<String>>`	`getFullParameterList(FacesContext ctx, String viewId, Map<String,List<String>> existingParameters)`
`Set<String>`	`getProtectedViewsUnmodifiable()` Return an unmodifiable `Set` of the protected views currently known to this `ViewHandler` instance.
`String`	`getRedirectURL(FacesContext context, String viewId, Map<String,List<String>> parameters, boolean includeViewParams)` Return a Jakarta Server Faces 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.
`String`	`getResourceURL(FacesContext context, String path)` This code is currently common to all `ViewHandlingStrategy` instances.
`ViewDeclarationLanguage`	`getViewDeclarationLanguage(FacesContext context, String viewId)` Return the `ViewDeclarationLanguage` instance used for this `ViewHandler` instance.
`Stream<String>`	`getViews(FacesContext context, String path, int maxDepth, ViewVisitOption... options)` Return a `Stream` possibly lazily populated by walking the view trees of every active `ViewDeclarationLanguage` rooted at a given initial path.
`Stream<String>`	`getViews(FacesContext context, String path, ViewVisitOption... options)` Return a `Stream` possibly lazily populated by walking the view trees of every active `ViewDeclarationLanguage` rooted at a given initial path.
`String`	`getWebsocketURL(FacesContext context, String channel)` 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 push handshake request to the `toExternalForm()` of that `URL` will select the argument `channel` for connecting the websocket push channel in the current view.
`void`	`initView(FacesContext context)` Call the default implementation of `ViewHandler.initView(javax.faces.context.FacesContext)`
`protected String`	`normalizeRequestURI(String uri, String mapping)` If the specified mapping is a prefix mapping, and the provided request URI (usually the value from `ExternalContext.getRequestServletPath()`) starts with `mapping + '/'`, prune the mapping from the URI and return it, otherwise, return the original URI.
`boolean`	`removeProtectedView(String urlPattern)` Remove the argument `urlPattern` from the thread safe `Set` of protected views for this application, if present in the `Set`.
`void`	`renderView(FacesContext context, UIViewRoot viewToRender)` Call `ViewDeclarationLanguage.renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot)` if the view can be rendered.
`UIViewRoot`	`restoreView(FacesContext context, String viewId)` Call `ViewDeclarationLanguage.restoreView(javax.faces.context.FacesContext, String)`.
`protected void`	`send404Error(FacesContext context)` Send `HttpServletResponse.SC_NOT_FOUND` (404) to the client.
`void`	`writeState(FacesContext context)` This code is currently common to all `ViewHandlingStrategy` instances.

Methods inherited from class javax.faces.application.ViewHandler
calculateCharacterEncoding

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

- Constructor Detail
  - MultiViewHandler
```
public MultiViewHandler()
```
- Method Detail
  - initView
```
public void initView(FacesContext context)
              throws FacesException
```
    Call the default implementation of ViewHandler.initView(javax.faces.context.FacesContext)
    
    Overrides:
    
    initView in class ViewHandler
    
    Parameters:
    
    context - the Faces context.
    
    Throws:
    
    FacesException - if a problem occurs setting the encoding, such as the UnsupportedEncodingException thrown by the underlying Jakarta Servlet or Portlet technology when the encoding is not supported.
    
    See Also:
    
    ViewHandler.initView(javax.faces.context.FacesContext)
  - restoreView
```
public UIViewRoot restoreView(FacesContext context,
                              String viewId)
```
    Call ViewDeclarationLanguage.restoreView(javax.faces.context.FacesContext, String).
    
    Specified by:
    
    restoreView in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request
    
    viewId - the view identifier for the current request
    
    Returns:
    
    the restored view root, or null.
    
    See Also:
    
    ViewHandler.restoreView(javax.faces.context.FacesContext, String)
  - createView
```
public UIViewRoot createView(FacesContext context,
                             String viewId)
```
    Derive the physical view ID (i.e. the physical resource) and call call ViewDeclarationLanguage.createView(javax.faces.context.FacesContext, String).
    
    Specified by:
    
    createView in class ViewHandler
    
    Parameters:
    
    context - the Faces context.
    
    viewId - the view id.
    
    Returns:
    
    the viewroot.
    
    See Also:
    
    ViewHandler.restoreView(javax.faces.context.FacesContext, String)
  - renderView
```
public void renderView(FacesContext context,
                       UIViewRoot viewToRender)
                throws IOException,
                       FacesException
```
    Call ViewDeclarationLanguage.renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot) if the view can be rendered.
    
    Specified by:
    
    renderView in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request
    
    viewToRender - the view to render
    
    Throws:
    
    IOException - if an input/output error occurs
    
    FacesException - if a Jakarta Servlet error occurs
    
    See Also:
    
    ViewHandler.renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot)
  - calculateLocale
```
public Locale calculateLocale(FacesContext context)
```
    This code is currently common to all ViewHandlingStrategy instances.
    
    Specified by:
    
    calculateLocale in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request
    
    Returns:
    
    the locale.
    
    See Also:
    
    ViewHandler.calculateLocale(javax.faces.context.FacesContext)
  - calculateRenderKitId
```
public String calculateRenderKitId(FacesContext context)
```
    This code is currently common to all ViewHandlingStrategy instances.
    
    Specified by:
    
    calculateRenderKitId in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request
    
    Returns:
    
    the render kit id.
    
    See Also:
    
    ViewHandler.calculateRenderKitId(javax.faces.context.FacesContext)
  - writeState
```
public void writeState(FacesContext context)
                throws IOException
```
    This code is currently common to all ViewHandlingStrategy instances.
    
    Specified by:
    
    writeState in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request
    
    Throws:
    
    IOException - if an input/output error occurs
    
    See Also:
    
    ViewHandler.writeState(javax.faces.context.FacesContext)
  - getActionURL
```
public String getActionURL(FacesContext context,
                           String viewId)
```
    This code is currently common to all ViewHandlingStrategy instances.
    
    Specified by:
    
    getActionURL in class ViewHandler
    
    Parameters:
    
    context - FacesContext for this request
    
    viewId - View identifier of the desired view
    
    Returns:
    
    the action url.
    
    See Also:
    
    ViewHandler.getActionURL(javax.faces.context.FacesContext, String)
  - getResourceURL
```
public String getResourceURL(FacesContext context,
                             String path)
```
    This code is currently common to all ViewHandlingStrategy instances.
    
    Specified by:
    
    getResourceURL in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request
    
    path - Resource path to convert to a URL
    
    Returns:
    
    the resource URL.
    
    See Also:
    
    ViewHandler.getResourceURL(javax.faces.context.FacesContext, String)
  - getWebsocketURL
```
public String getWebsocketURL(FacesContext context,
                              String channel)
```
    Description copied from class: ViewHandler
    
    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 push handshake request to the toExternalForm() of that URL will select the argument channel for connecting the websocket push channel in the current view. It must match the PushContext.URI_PREFIX of the endpoint.
    
    Specified by:
    
    getWebsocketURL in class ViewHandler
    
    Parameters:
    
    context - FacesContext for the current request.
    
    channel - The channel name of the websocket.
    
    Returns:
    
    the websocket URL.
    
    See Also:
    
    PushContext.URI_PREFIX
  - getBookmarkableURL
```
public String getBookmarkableURL(FacesContext context,
                                 String viewId,
                                 Map<String,List<String>> parameters,
                                 boolean includeViewParams)
```
    Description copied from class: ViewHandler
    
    Return a Jakarta Server Faces action URL derived from the viewId argument that is suitable to be used as the target of a link in a Jakarta Server Faces response. Compliant implementations must implement this method as specified in section JSF.7.6.2. The default implementation simply calls through to ViewHandler.getActionURL(javax.faces.context.FacesContext, java.lang.String), passing the arguments context and viewId.
    
    Overrides:
    
    getBookmarkableURL in class ViewHandler
    
    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
    
    Returns:
    
    the bookmarkable URL.
  - addProtectedView
```
public void addProtectedView(String urlPattern)
```
    Description copied from class: ViewHandler
    
    Add the argument urlPattern to the thread safe Set of protected views for this application. Compliant implementations make it so a subsequent call to ViewHandler.getProtectedViewsUnmodifiable() contains the argument. The runtime must support calling this method at any time after application startup. The default implementation takes no action.
    
    Overrides:
    
    addProtectedView in class ViewHandler
    
    Parameters:
    
    urlPattern - the url-pattern to add.
  - getProtectedViewsUnmodifiable
```
public Set<String> getProtectedViewsUnmodifiable()
```
    Description copied from class: ViewHandler
    
    Return an unmodifiable Set of the protected views currently known to this ViewHandler instance. Compliant implementations must return a Set that is the concatenation of the contents of all the <url-pattern> elements within all the <protected-views> in all of the application configuration resources in the current application. The runtime must support calling this method at any time after application startup. The default implementation returns an unmodifiable empty Set.
    
    Overrides:
    
    getProtectedViewsUnmodifiable in class ViewHandler
    
    Returns:
    
    the unmodifiable set of protected views.
  - removeProtectedView
```
public boolean removeProtectedView(String urlPattern)
```
    Description copied from class: ViewHandler
    
    Remove the argument urlPattern from the thread safe Set of protected views for this application, if present in the Set. If the argument urlPattern is not present in the Set, this method has no effect. Compliant implementations must make it so a subsequent call to ViewHandler.getProtectedViewsUnmodifiable() does not contain the argument. The runtime must support calling this method at any time after application startup. Returns true if this Set contained the argument. The default implementation takes no action and returns false.
    
    Overrides:
    
    removeProtectedView in class ViewHandler
    
    Parameters:
    
    urlPattern - the url-pattern to remove.
    
    Returns:
    
    true if in the Set, false otherwise.
  - getRedirectURL
```
public String getRedirectURL(FacesContext context,
                             String viewId,
                             Map<String,List<String>> parameters,
                             boolean includeViewParams)
```
    Description copied from class: ViewHandler
    
    Return a Jakarta Server Faces 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. Compliant implementations must implement this method as specified in section JSF.7.6.2. The default implementation simply calls through to ViewHandler.getActionURL(javax.faces.context.FacesContext, java.lang.String), passing the arguments context and viewId.
    
    Overrides:
    
    getRedirectURL in class ViewHandler
    
    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
    
    Returns:
    
    the redirect URL.
    
    See Also:
    
    ViewHandler.getRedirectURL(javax.faces.context.FacesContext, String, java.util.Map, boolean)
  - getViewDeclarationLanguage
```
public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context,
                                                          String viewId)
```
    Description copied from class: ViewHandler
    
    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.
    
    Overrides:
    
    getViewDeclarationLanguage in class ViewHandler
    
    Parameters:
    
    context - the FacesContext for this request.
    
    viewId - the logical view id, as returned from ViewHandler.deriveLogicalViewId(javax.faces.context.FacesContext, java.lang.String) for which the ViewDeclarationLanguage should be returned.
    
    Returns:
    
    the ViewDeclarationLanguage, or null.
    
    See Also:
    
    ViewHandler.getViewDeclarationLanguage(javax.faces.context.FacesContext, String)
  - getViews
```
public Stream<String> getViews(FacesContext context,
                               String path,
                               ViewVisitOption... options)
```
    Description copied from class: ViewHandler
    Return a Stream possibly lazily populated by walking the view trees of every active ViewDeclarationLanguage rooted at a given initial path. The view tree of every ViewDeclarationLanguage is individually traversed breadth-first as per the contract of ViewDeclarationLanguage.getViews(FacesContext, String, int, ViewVisitOption...). The elements in the stream are logical view ids.
    
    This method works as if invoking it were equivalent to evaluating the expression:
    getViews(facesContext, start, Integer.MAX_VALUE, options)
    Put differently, it visits all levels of the view tree.
    In case more than one active ViewDeclarationLanguage is present, the order in which view ids from each ViewDeclarationLanguage appear in the stream is undetermined, except for the guarantee that every individual ViewDeclarationLanguage is traversed breadth-first.
    Overrides:
    
    getViews in class ViewHandler
    
    Parameters:
    
    context - The FacesContext for this request.
    
    path - The initial path from which to start looking for view ids.
    
    options - The options to influence the traversal. See ViewVisitOption for details on those.
    
    Returns:
    
    the Stream of view ids
  - getViews
```
public Stream<String> getViews(FacesContext context,
                               String path,
                               int maxDepth,
                               ViewVisitOption... options)
```
    Description copied from class: ViewHandler
    
    Return a Stream possibly lazily populated by walking the view trees of every active ViewDeclarationLanguage rooted at a given initial path. The view tree of every ViewDeclarationLanguage is individually traversed breadth-first as per the contract of ViewDeclarationLanguage.getViews(FacesContext, String, int, ViewVisitOption...). The elements in the stream are logical view ids.
    
    The maxDepth parameter is the maximum depth of directory levels to visit for each ViewDeclarationLanguage beyond the initial path, which is always visited. The value is relative to the root (/), not to the given initial path. E.g. given maxDepth = 3 and initial path /foo/, visiting will proceed up to /foo/bar/, where / counts as depth 1, /foo/ as depth 2 and /foo/bar/ as depth 3. A value lower or equal to the depth of the initial path means that only the initial path is visited. A value of MAX_VALUE may be used to indicate that all levels should be visited.
    In case more than one active ViewDeclarationLanguage is present, the order in which view ids from each ViewDeclarationLanguage appear in the stream is undetermined, except for the guarantee that every individual ViewDeclarationLanguage is traversed breadth-first.
    
    Overrides:
    
    getViews in class ViewHandler
    
    Parameters:
    
    context - The FacesContext for this request.
    
    path - The initial path from which to start looking for view ids.
    
    maxDepth - The absolute maximum depth of nested directories to visit counted from the root (/).
    
    options - The options to influence the traversal. See ViewVisitOption for details on those.
    
    Returns:
    
    the Stream of view ids
  - deriveViewId
```
public String deriveViewId(FacesContext context,
                           String requestViewId)
```
    Description copied from class: ViewHandler
    
    Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2.
    
    This method should work correctly when the FacesServlet is invoked via either a path mapping, extension mapping or an exact match (mapping) as defined by Servlet.12.2. Note that path mapping is also commonly known as prefix mapping (e.g. "/faces/*") and extension mapping as suffix mapping (e.g. "*.xhtml"). An exact match is possible where there's a servlet mapping with an exact URL pattern such as "/foo".
    
    The default implementation of this method simply returns requestViewId unchanged.
    
    Overrides:
    
    deriveViewId in class ViewHandler
    
    Parameters:
    
    context - the FacesContext for this request
    
    requestViewId - the viewId to derive,
    
    Returns:
    
    the derived view id.
  - deriveLogicalViewId
```
public String deriveLogicalViewId(FacesContext context,
                                  String requestViewId)
```
    Description copied from class: ViewHandler
    
    Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2. Note that unlike deriveViewId(), this method does not require that a physical view be present.
    
    This method should work correctly when the FacesServlet is invoked via either a path mapping, extension mapping or an exact match (mapping) as defined by Servlet.12.2. Note that path mapping is also commonly known as prefix mapping (e.g. "/faces/*") and extension mapping as suffix mapping (e.g. "*.xhtml"). An exact match is possible where there's a servlet mapping with an exact URL pattern such as "/foo".
    
    The default implementation of this method simply returns requestViewId unchanged.
    
    Overrides:
    
    deriveLogicalViewId in class ViewHandler
    
    Parameters:
    
    context - the FacesContext for this request
    
    requestViewId - the viewId to derive,
    
    Returns:
    
    the derived logical view id.
  - normalizeRequestURI
```
protected String normalizeRequestURI(String uri,
                                     String mapping)
```
    If the specified mapping is a prefix mapping, and the provided request URI (usually the value from ExternalContext.getRequestServletPath()) starts with mapping + '/', prune the mapping from the URI and return it, otherwise, return the original URI.
    
    Parameters:
    
    uri - the servlet request path
    
    mapping - the FacesServlet mapping used for this request
    
    Returns:
    
    the URI without additional FacesServlet mappings
    
    Since:
    
    1.2
  - convertViewId
```
protected String convertViewId(FacesContext context,
                               String viewId)
```
    Adjust the viewID per the requirements of renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot).
    
    Parameters:
    
    context - current FacesContext
    
    viewId - incoming view ID
    
    Returns:
    
    the view ID with an altered suffix mapping (if necessary)
  - derivePhysicalViewId
```
protected String derivePhysicalViewId(FacesContext ctx,
                                      String requestViewId,
                                      boolean checkPhysical)
```
  - getFullParameterList
```
protected Map<String,List<String>> getFullParameterList(FacesContext ctx,
                                                        String viewId,
                                                        Map<String,List<String>> existingParameters)
```
  - addViewParameters
```
protected void addViewParameters(FacesContext ctx,
                                 String viewId,
                                 Map<String,List<String>> existingParameters)
```
  - findMatch
```
protected Locale findMatch(FacesContext context,
                           Locale pref)
```
    Attempts to find a matching locale based on pref and list of supported locales, using the matching algorithm as described in JSTL 8.3.2.
    
    Parameters:
    
    context - the FacesContext for the current request
    
    pref - the preferred locale
    
    Returns:
    
    the Locale based on pref and the matching alogritm specified in JSTL 8.3.2
  - send404Error
```
protected void send404Error(FacesContext context)
```
    Send HttpServletResponse.SC_NOT_FOUND (404) to the client.
    
    Parameters:
    
    context - the FacesContext for the current request

Class MultiViewHandler

Field Summary

Fields inherited from class javax.faces.application.ViewHandler

Constructor Summary

Method Summary

Methods inherited from class javax.faces.application.ViewHandler

Methods inherited from class java.lang.Object

Constructor Detail

MultiViewHandler

Method Detail

initView

restoreView

createView

renderView

calculateLocale

calculateRenderKitId

writeState

getActionURL

getResourceURL

getWebsocketURL

getBookmarkableURL

addProtectedView

getProtectedViewsUnmodifiable

removeProtectedView

getRedirectURL

getViewDeclarationLanguage

getViews

getViews

deriveViewId

deriveLogicalViewId

normalizeRequestURI

convertViewId

derivePhysicalViewId

getFullParameterList

addViewParameters

findMatch

send404Error