Module jakarta.faces

Package com.sun.faces.application.view

Class MultiViewHandler

java.lang.Object

jakarta.faces.application.ViewHandler

com.sun.faces.application.view.MultiViewHandler

public class MultiViewHandler
extends ViewHandler

This ViewHandler implementation handles the Facelets VDL-based views.

Field Summary

Fields inherited from class jakarta.faces.application.ViewHandler

CHARACTER_ENCODING_KEY, DEFAULT_FACELETS_SUFFIX, DEFAULT_SUFFIX, DEFAULT_SUFFIX_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	Description
MultiViewHandler()

Method Summary

Modifier and Type	Method	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(jakarta.faces.context.FacesContext, jakarta.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 section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document.
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 section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document.
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 Faces action URL derived from the viewId argument that is suitable to be used as the target of a link in a Jakarta 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 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(jakarta.faces.context.FacesContext)
protected String	normalizeRequestURI(String viewId, String mapping)	If the specified mapping is a prefix mapping, and the provided request URI (sometimes 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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIViewRoot) if the view can be rendered.
UIViewRoot	restoreView(FacesContext context, String viewId)	Call ViewDeclarationLanguage.restoreView(jakarta.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 jakarta.faces.application.ViewHandler

calculateCharacterEncoding

Methods inherited from class java.lang.Object

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

Constructor Details

MultiViewHandler

public MultiViewHandler()

Method Details

initView

public void initView(FacesContext context)
              throws FacesException

Call the default implementation of ViewHandler.initView(jakarta.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(jakarta.faces.context.FacesContext)

restoreView

public UIViewRoot restoreView(FacesContext context,
 String viewId)

Call ViewDeclarationLanguage.restoreView(jakarta.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(jakarta.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(jakarta.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(jakarta.faces.context.FacesContext, String)

renderView

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

Call ViewDeclarationLanguage.renderView(jakarta.faces.context.FacesContext, jakarta.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(jakarta.faces.context.FacesContext, jakarta.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(jakarta.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(jakarta.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(jakarta.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(jakarta.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(jakarta.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 Faces action URL derived from the viewId argument that is suitable to be used as the target of a link in a Jakarta Faces response. Compliant implementations must implement this method as specified in section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document. The default implementation simply calls through to ViewHandler.getActionURL(jakarta.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 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 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document. The default implementation simply calls through to ViewHandler.getActionURL(jakarta.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(jakarta.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(jakarta.faces.context.FacesContext, java.lang.String) for which the ViewDeclarationLanguage should be returned.

Returns:

the ViewDeclarationLanguage, or null.

See Also:

• ViewHandler.getViewDeclarationLanguage(jakarta.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 section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document.

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 section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document. 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.

derivePhysicalViewId

protected String derivePhysicalViewId(FacesContext ctx,
 String requestViewId,
 boolean checkPhysical)

normalizeRequestURI

protected String normalizeRequestURI(String viewId,
 String mapping)

If the specified mapping is a prefix mapping, and the provided request URI (sometimes the value from ExternalContext.getRequestServletPath()) starts with mapping, prune the mapping from the URI and return it, otherwise, return the original URI.

Parameters:

viewId - something resembling a view id, can come from the request or from the navigation handler.

mapping - the FacesServlet mapping used for this request with the "/*" removed, e.g. /faces instead of /faces/*

Returns:

the viewId without additional prefix FacesServlet mappings

Since:

1.2

convertViewId

protected String convertViewId(FacesContext context,
 String viewId)

Adjust the viewID per the requirements of renderView(jakarta.faces.context.FacesContext, jakarta.faces.component.UIViewRoot).

Parameters:

context - current FacesContext

viewId - incoming view ID

Returns:

the view ID with an altered suffix mapping (if necessary)

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