Jakarta EE 11.0.0 · jakarta.faces.application.ViewHandler

Modifier and Type	Field and Description
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.
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.
public static final String	DEFAULT_SUFFIX Deprecated for removal since 4.0. Use `DEFAULT_FACELETS_SUFFIX` instead. This is not anymore used since removal of support for Jakarta Pages.
public static final String	DEFAULT_SUFFIX_PARAM_NAME Deprecated for removal since 4.0. Use `FACELETS_SUFFIX_PARAM_NAME` instead. This is not anymore used since removal of support for Jakarta Pages.
public static final String	FACELETS_BUFFER_SIZE_PARAM_NAME The buffer size to set on the response when the ResponseWriter is generated.
public static final String	FACELETS_DECORATORS_PARAM_NAME A semicolon (;) delimitted list of class names of type jakarta.faces.view.facelets.TagDecorator, with a no-argument constructor.
public static final String	FACELETS_LIBRARIES_PARAM_NAME If this param is set, the runtime must interpret it as a semicolon (;) separated list of paths, starting with "/" (without the quotes).
public static final String	FACELETS_REFRESH_PERIOD_PARAM_NAME When a page is requested, what interval in seconds should the compiler check for changes.
public static final String	FACELETS_SKIP_COMMENTS_PARAM_NAME If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the runtime must ensure that any XML comments in the Facelets source page are not delivered to the client.
public static final String	FACELETS_SUFFIX_PARAM_NAME Allow the web application to define a list of alternate suffixes for Facelet based XHTML pages containing Jakarta Faces content.
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.
private static final Logger	log

Access	Constructor and Description
public	ViewHandler()

Method Summary

Modifier and Type	Method and Description
public void	addProtectedView(String the url-pattern to add. urlPattern) Add the argument `urlPattern` to the thread safe `Set` of protected views for this application.
public String	Returns: the character encoding, or `null` calculateCharacterEncoding(FacesContext the Faces context. context) Returns the correct character encoding to be used for this request.
public abstract Locale	Returns: the locale. calculateLocale(FacesContext `FacesContext` for the current request context) Returns an appropriate `Locale` to use for this and subsequent requests for the current client.
public abstract String	Returns: the render kit id. calculateRenderKitId(FacesContext `FacesContext` for the current request context) Return an appropriate `renderKitId` for this and subsequent requests from the current client.
public abstract UIViewRoot	Returns: the viewroot. createView(FacesContext the Faces context. context, String the view id. viewId) Create and return a new `UIViewRoot` instance initialized with information from the argument `FacesContext` and `viewId`.
public String	Returns: the derived logical view id. deriveLogicalViewId(FacesContext the `FacesContext` for this request context, String the `viewId` to derive, 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.
public String	Returns: the derived view id. deriveViewId(FacesContext the `FacesContext` for this request context, String the `viewId` to derive, 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.
public abstract String	Returns: the action url. getActionURL(FacesContext `FacesContext` for this request context, String View identifier of the desired view 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 Jakarta Faces lifecycle.
public String	Returns: the bookmarkable URL. getBookmarkableURL(FacesContext The FacesContext processing this request context, String The view identifier of the target page viewId, Map<String, List<String>> A mapping of parameter names to one or more values parameters, boolean A flag indicating whether view parameters should be encoded into this URL 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.
public Set<String>	Returns: the unmodifiable set of protected views. getProtectedViewsUnmodifiable() Return an unmodifiable `Set` of the protected views currently known to this `ViewHandler` instance.
public String	Returns: the redirect URL. getRedirectURL(FacesContext The FacesContext processing this request context, String The view identifier of the target page viewId, Map<String, List<String>> A mapping of parameter names to one or more values parameters, boolean A flag indicating whether view parameters should be encoded into this URL 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.
public abstract String	Returns: the resource URL. getResourceURL(FacesContext `FacesContext` for the current request context, String Resource path to convert to a URL 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.
public ViewDeclarationLanguage	Returns: the ViewDeclarationLanguage, or null. getViewDeclarationLanguage(FacesContext the `FacesContext` for this request. context, String the logical view id, as returned from `deriveLogicalViewId` for which the `ViewDeclarationLanguage` should be returned. viewId) Return the `ViewDeclarationLanguage` instance used for this `ViewHandler` instance.
public Stream<String>	Returns: the `Stream` of view ids getViews(FacesContext The `FacesContext` for this request. facesContext, String The initial path from which to start looking for view ids. path, int The absolute maximum depth of nested directories to visit counted from the root (`/`). maxDepth, ViewVisitOption... The options to influence the traversal. See `ViewVisitOption` for details on those. options) Return a `Stream` possibly lazily populated by walking the view trees of every active `ViewDeclarationLanguage` rooted at a given initial path.
public Stream<String>	Returns: the `Stream` of view ids getViews(FacesContext The `FacesContext` for this request. facesContext, String The initial path from which to start looking for view ids. path, ViewVisitOption... The options to influence the traversal. See `ViewVisitOption` for details on those. options) Return a `Stream` possibly lazily populated by walking the view trees of every active `ViewDeclarationLanguage` rooted at a given initial path.
public abstract String	Returns: the websocket URL. getWebsocketURL(FacesContext `FacesContext` for the current request. context, String The channel name of the websocket. 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.
public void	initView(FacesContext the Faces context. context) Initialize the view for the request processing lifecycle.
public boolean	Returns: `true` if in the `Set`, `false` otherwise. removeProtectedView(String the url-pattern to remove. urlPattern) Remove the argument `urlPattern` from the thread safe `Set` of protected views for this application, if present in the `Set`.
public abstract void	renderView(FacesContext `FacesContext` for the current request context, UIViewRoot the view to render viewToRender) Perform whatever actions are required to render the response view to the response object associated with the current `FacesContext`.
public abstract UIViewRoot	Returns: the restored view root, or null. restoreView(FacesContext `FacesContext` for the current request context, String the view identifier for the current request viewId) Perform whatever actions are required to restore the view associated with the specified `FacesContext` and `viewId`.
public abstract void	writeState(FacesContext `FacesContext` for the current request context) Take any appropriate action to either immediately write out the current state information (by calling `StateManager#writeState`, or noting where state information should later be written.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

CHARACTER_ENCODING_KEY	back to summary
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.

DEFAULT_FACELETS_SUFFIX	back to summary
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

DEFAULT_SUFFIX	back to summary
public static final String DEFAULT_SUFFIX Deprecated for removal since 4.0. Use `DEFAULT_FACELETS_SUFFIX` instead. This is not anymore used since removal of support for Jakarta Pages. Annotations @Deprecated since:4.0 forRemoval:true

DEFAULT_SUFFIX_PARAM_NAME	back to summary
public static final String DEFAULT_SUFFIX_PARAM_NAME Deprecated for removal since 4.0. Use `FACELETS_SUFFIX_PARAM_NAME` instead. This is not anymore used since removal of support for Jakarta Pages. Annotations @Deprecated since:4.0 forRemoval:true

FACELETS_BUFFER_SIZE_PARAM_NAME	back to summary
public static final String FACELETS_BUFFER_SIZE_PARAM_NAME The buffer size to set on the response when the ResponseWriter is generated. By default the value is 1024. A value of -1 will not assign a buffer size on the response. This should be increased if you are using development mode in order to guarantee that the response isn't partially rendered when an error is generated. Since 2.0

FACELETS_DECORATORS_PARAM_NAME	back to summary
public static final String FACELETS_DECORATORS_PARAM_NAME A semicolon (;) delimitted list of class names of type jakarta.faces.view.facelets.TagDecorator, with a no-argument constructor. These decorators will be loaded when the first request for a Facelets VDL view hits the ViewHandler for page compilation. Since 2.0

FACELETS_LIBRARIES_PARAM_NAME	back to summary
public static final String FACELETS_LIBRARIES_PARAM_NAME If this param is set, the runtime must interpret it as a semicolon (;) separated list of paths, starting with "/" (without the quotes). The runtime must interpret each entry in the list as a path relative to the web application root and interpret the file found at that path as a facelet tag library, conforming to the facelet taglibrary schema and expose the tags therein according to Section "Facelet Tag Library mechanism". Since 2.0

FACELETS_REFRESH_PERIOD_PARAM_NAME	back to summary
public static final String FACELETS_REFRESH_PERIOD_PARAM_NAME When a page is requested, what interval in seconds should the compiler check for changes. If you don't want the compiler to check for changes once the page is compiled, then use a value of -1. Setting a low refresh period helps during development to be able to edit pages in a running application. If this value is not specified, then the default depends on `jakarta.faces.application.ProjectStage`. If it is `Production`, then runtime must act as if it is set to -1, else the runtime must act as if it is set to 0. Since 2.0

FACELETS_SKIP_COMMENTS_PARAM_NAME	back to summary
public static final String FACELETS_SKIP_COMMENTS_PARAM_NAME If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the runtime must ensure that any XML comments in the Facelets source page are not delivered to the client. Since 2.0

FACELETS_SUFFIX_PARAM_NAME	back to summary
public static final String FACELETS_SUFFIX_PARAM_NAME Allow the web application to define a list of alternate suffixes for Facelet based XHTML pages containing Jakarta Faces 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_FACELETS_SUFFIX` Since 2.0

FACELETS_VIEW_MAPPINGS_PARAM_NAME	back to summary
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.xhtml`. Since 2.0

log	back to summary
private static final Logger log

ViewHandler	back to summary
public ViewHandler()

Method Detail

addProtectedView back to summary

addProtectedView	back to summary
public void addProtectedView(String urlPattern) Add the argument `urlPattern` to the thread safe `Set` of protected views for this application. Compliant implementations make it so a subsequent call to `getProtectedViewsUnmodifiable` contains the argument. The runtime must support calling this method at any time after application startup. The default implementation takes no action. Parameters urlPattern:String the url-pattern to add. Since 2.2

public void addProtectedView(String urlPattern)

Add the argument urlPattern to the thread safe Set of protected views for this application. Compliant implementations make it so a subsequent call to getProtectedViewsUnmodifiable contains the argument. The runtime must support calling this method at any time after application startup. The default implementation takes no action.

Parameters

urlPattern:String: the url-pattern to add.

Since

2.2

calculateCharacterEncoding back to summary

calculateCharacterEncoding	back to summary
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 `ViewHandler#CHARACTER_ENCODING_KEY`. If present, return the value, converted to String. Otherwise, return `null` Parameters context:FacesContext the Faces context. Returns:String the character encoding, or `null` Since 1.2

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 ViewHandler#CHARACTER_ENCODING_KEY. If present, return the value, converted to String.
Otherwise, return null

Parameters

context:FacesContext: the Faces context.

Returns:String

the character encoding, or null

Since

1.2

calculateLocale back to summary

calculateLocale	back to summary
public abstract Locale calculateLocale(FacesContext context) Returns an appropriate `Locale` to use for this and subsequent requests for the current client. Parameters context:FacesContext `FacesContext` for the current request Returns:Locale the locale. Exceptions NullPointerException: if `context` is `null`

public abstract Locale calculateLocale(FacesContext context)

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

Parameters

context:FacesContext: FacesContext for the current request

Returns:Locale

the locale.

Exceptions

NullPointerException:: if context is null

calculateRenderKitId back to summary

calculateRenderKitId	back to summary
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 `jakarta.faces.render.RenderKitFactory#HTML_BASIC_RENDER_KIT`. Parameters context:FacesContext `FacesContext` for the current request Returns:String the render kit id. Exceptions NullPointerException: if `context` is `null`

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 jakarta.faces.render.RenderKitFactory#HTML_BASIC_RENDER_KIT.

Parameters

context:FacesContext: FacesContext for the current request

Returns:String

the render kit id.

Exceptions

NullPointerException:: if context is null

createView back to summary

createView	back to summary
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`, which must be called by this method. Parameters context:FacesContext the Faces context. viewId:String the view id. Returns:UIViewRoot the viewroot. Exceptions NullPointerException: if `context` is `null`

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, which must be called by this method.

Parameters

context:FacesContext: the Faces context.
viewId:String: the view id.

Returns:UIViewRoot

the viewroot.

Exceptions

NullPointerException:: if context is null

deriveLogicalViewId back to summary

deriveLogicalViewId	back to summary
public 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. 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. Parameters context:FacesContext the `FacesContext` for this request requestViewId:String the `viewId` to derive, Returns:String the derived logical view id. Since 2.1

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

Parameters

context:FacesContext: the FacesContext for this request
requestViewId:String: the viewId to derive,

Returns:String

the derived logical view id.

Since

2.1

deriveViewId back to summary

deriveViewId	back to summary
public 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. 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. Parameters context:FacesContext the `FacesContext` for this request requestViewId:String the `viewId` to derive, Returns:String the derived view id. Since 2.0

public String deriveViewId(FacesContext context, String requestViewId)

The default implementation of this method simply returns requestViewId unchanged.

Parameters

context:FacesContext: the FacesContext for this request
requestViewId:String: the viewId to derive,

Returns:String

the derived view id.

Since

2.0

getActionURL back to summary

getActionURL	back to summary
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 Jakarta Faces lifecycle. Please see section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document for the complete specification, especially for details related to view protection using the `jakarta.faces.render.ResponseStateManager#NON_POSTBACK_VIEW_TOKEN_PARAM` and the behavior when the current request is to a URL for which the FacesServlet has an exact mapping as defined by Servlet.12.2. Parameters context:FacesContext `FacesContext` for this request viewId:String View identifier of the desired view Returns:String the action url. Exceptions IllegalArgumentException: if `viewId` is not valid for this `ViewHandler`, or does not start with "/". NullPointerException: if `context` or `viewId` is `null`.

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 Jakarta Faces lifecycle. Please see section 7.6.2 "Default ViewHandler Implementation" of the Jakarta Faces Specification Document for the complete specification, especially for details related to view protection using the jakarta.faces.render.ResponseStateManager#NON_POSTBACK_VIEW_TOKEN_PARAM and the behavior when the current request is to a URL for which the FacesServlet has an exact mapping as defined by Servlet.12.2.

Parameters

context:FacesContext: FacesContext for this request
viewId:String: View identifier of the desired view

Returns:String

the action url.

Exceptions

IllegalArgumentException:: if viewId is not valid for this ViewHandler, or does not start with "/".
NullPointerException:: if context or viewId is null.

getBookmarkableURL back to summary

getBookmarkableURL	back to summary
public 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. 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 `getActionURL`, passing the arguments `context` and `viewId`. Parameters context:FacesContext The FacesContext processing this request viewId:String The view identifier of the target page parameters:Map<String, List<String>> A mapping of parameter names to one or more values includeViewParams:boolean A flag indicating whether view parameters should be encoded into this URL Returns:String the bookmarkable URL. Since 2.0

public 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. 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 getActionURL, passing the arguments context and viewId.

Parameters

context:FacesContext: The FacesContext processing this request
viewId:String: The view identifier of the target page
parameters:Map<String, List<String>>: A mapping of parameter names to one or more values
includeViewParams:boolean: A flag indicating whether view parameters should be encoded into this URL

Returns:String

the bookmarkable URL.

Since

2.0

getProtectedViewsUnmodifiable back to summary

getProtectedViewsUnmodifiable	back to summary
public Set<String> getProtectedViewsUnmodifiable() 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`. Returns:Set<String> the unmodifiable set of protected views. Since 2.2

public Set<String> getProtectedViewsUnmodifiable()

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.

Returns:Set<String>: the unmodifiable set of protected views.
Since: 2.2

getRedirectURL back to summary

getRedirectURL	back to summary
public 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. 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 `getActionURL`, passing the arguments `context` and `viewId`. Parameters context:FacesContext The FacesContext processing this request viewId:String The view identifier of the target page parameters:Map<String, List<String>> A mapping of parameter names to one or more values includeViewParams:boolean A flag indicating whether view parameters should be encoded into this URL Returns:String the redirect URL. Since 2.0

public 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. 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 getActionURL, passing the arguments context and viewId.

Parameters

context:FacesContext: The FacesContext processing this request
viewId:String: The view identifier of the target page
parameters:Map<String, List<String>>: A mapping of parameter names to one or more values
includeViewParams:boolean: A flag indicating whether view parameters should be encoded into this URL

Returns:String

the redirect URL.

Since

2.0

getResourceURL back to summary

getResourceURL	back to summary
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 `FacesContext` for the current request path:String Resource path to convert to a URL Returns:String the resource URL. Exceptions IllegalArgumentException: if `viewId` is not valid for this `ViewHandler`. NullPointerException: if `context` or `path` is `null`.

public abstract String getResourceURL(FacesContext context, String path)

Parameters

context:FacesContext: FacesContext for the current request
path:String: Resource path to convert to a URL

Returns:String

the resource URL.

Exceptions

IllegalArgumentException:: if viewId is not valid for this ViewHandler.
NullPointerException:: if context or path is null.

getViewDeclarationLanguage back to summary

getViewDeclarationLanguage	back to summary
public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context, String viewId) Return the `ViewDeclarationLanguage` instance used for this `ViewHandler` instance. The default implementation must use `jakarta.faces.view.ViewDeclarationLanguageFactory#getViewDeclarationLanguage` 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. Parameters context:FacesContext the `FacesContext` for this request. viewId:String the logical view id, as returned from `deriveLogicalViewId` for which the `ViewDeclarationLanguage` should be returned. Returns:ViewDeclarationLanguage the ViewDeclarationLanguage, or null. Since 2.0

public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context, String viewId)

Return the ViewDeclarationLanguage instance used for this ViewHandler instance.

The default implementation must use jakarta.faces.view.ViewDeclarationLanguageFactory#getViewDeclarationLanguage 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.

Parameters

context:FacesContext: the FacesContext for this request.
viewId:String: the logical view id, as returned from deriveLogicalViewId for which the ViewDeclarationLanguage should be returned.

Returns:ViewDeclarationLanguage

the ViewDeclarationLanguage, or null.

Since

2.0

getViews back to summary

getViews	back to summary
public Stream<String> getViews(FacesContext facesContext, 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. 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. Parameters facesContext:FacesContext The `FacesContext` for this request. path:String The initial path from which to start looking for view ids. maxDepth:int The absolute maximum depth of nested directories to visit counted from the root (`/`). options:ViewVisitOption[] The options to influence the traversal. See `ViewVisitOption` for details on those. Returns:Stream<String> the `Stream` of view ids Since 2.3

public Stream<String> getViews(FacesContext facesContext, 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. 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.

Parameters

facesContext:FacesContext: The FacesContext for this request.
path:String: The initial path from which to start looking for view ids.
maxDepth:int: The absolute maximum depth of nested directories to visit counted from the root (/).
options:ViewVisitOption[]: The options to influence the traversal. See ViewVisitOption for details on those.

Returns:Stream<String>

the Stream of view ids

Since

2.3

getViews back to summary

getViews	back to summary
public Stream<String> getViews(FacesContext facesContext, 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. 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. Parameters facesContext:FacesContext The `FacesContext` for this request. path:String The initial path from which to start looking for view ids. options:ViewVisitOption[] The options to influence the traversal. See `ViewVisitOption` for details on those. Returns:Stream<String> the `Stream` of view ids Since 2.3

public Stream<String> getViews(FacesContext facesContext, String path, ViewVisitOption... options)

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.

Parameters

facesContext:FacesContext: The FacesContext for this request.
path:String: The initial path from which to start looking for view ids.
options:ViewVisitOption[]: The options to influence the traversal. See ViewVisitOption for details on those.

Returns:Stream<String>

the Stream of view ids

Since

2.3

getWebsocketURL back to summary

getWebsocketURL	back to summary
public abstract 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. It must match the `PushContext#URI_PREFIX` of the endpoint. Parameters context:FacesContext `FacesContext` for the current request. channel:String The channel name of the websocket. Returns:String the websocket URL. Exceptions NullPointerException: if `context` or `channel` is `null`. See Also `PushContext#URI_PREFIX`

public abstract String getWebsocketURL(FacesContext context, String channel)

Parameters

context:FacesContext: FacesContext for the current request.
channel:String: The channel name of the websocket.

Returns:String

the websocket URL.

Exceptions

NullPointerException:: if context or channel is null.

See Also

PushContext#URI_PREFIX

initView back to summary

initView	back to summary
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` and pass the result, if non-`null`, into the `ExternalContext#setRequestCharacterEncoding` method. If `ExternalContext#getRequestCharacterEncoding` returns non-`null` take no action. Parameters context:FacesContext the Faces context. Exceptions 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.

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 and pass the result, if non-null, into the ExternalContext#setRequestCharacterEncoding method. If ExternalContext#getRequestCharacterEncoding returns non-null take no action.

Parameters

context:FacesContext: the Faces context.

Exceptions

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.

removeProtectedView back to summary

removeProtectedView	back to summary
public boolean removeProtectedView(String urlPattern) 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 `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`. Parameters urlPattern:String the url-pattern to remove. Returns:boolean `true` if in the `Set`, `false` otherwise. Since 2.2

public boolean removeProtectedView(String urlPattern)

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

Parameters

urlPattern:String: the url-pattern to remove.

Returns:boolean

true if in the Set, false otherwise.

Since

2.2

renderView back to summary

renderView	back to summary
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` method, returning the result and not swallowing any exceptions thrown by that method. Parameters context:FacesContext `FacesContext` for the current request viewToRender:UIViewRoot the view to render Exceptions IOException: if an input/output error occurs FacesException: if a Jakarta Servlet error occurs NullPointerException: if `context` or `viewToRender` is `null`

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 method, returning the result and not swallowing any exceptions thrown by that method.

Parameters

context:FacesContext: FacesContext for the current request
viewToRender:UIViewRoot: the view to render

Exceptions

IOException:: if an input/output error occurs
FacesException:: if a Jakarta Servlet error occurs
NullPointerException:: if context or viewToRender is null

restoreView back to summary

restoreView	back to summary
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` method, returning the result and not swallowing any exceptions thrown by that method. Parameters context:FacesContext `FacesContext` for the current request viewId:String the view identifier for the current request Returns:UIViewRoot the restored view root, or null. Exceptions NullPointerException: if `context` is `null` FacesException: if a Jakarta Servlet error occurs

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 method, returning the result and not swallowing any exceptions thrown by that method.

Parameters

context:FacesContext: FacesContext for the current request
viewId:String: the view identifier for the current request

Returns:UIViewRoot

the restored view root, or null.

Exceptions

NullPointerException:: if context is null
FacesException:: if a Jakarta Servlet error occurs

writeState back to summary

writeState	back to summary
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`, 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` and then written into the `Ajax` response during final encoding (`jakarta.faces.context.PartialViewContext#processPartial(jakarta.faces.event.PhaseId)`) . Parameters context:FacesContext `FacesContext` for the current request Exceptions IOException: if an input/output error occurs NullPointerException: if `context` is `null`

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, 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 and then written into the Ajax response during final encoding (jakarta.faces.context.PartialViewContext#processPartial(jakarta.faces.event.PhaseId)) .

Parameters

context:FacesContext: FacesContext for the current request

Exceptions

IOException:: if an input/output error occurs
NullPointerException:: if context is null

public abstract Class ViewHandler

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail