Class ViewHandler
- Direct Known Subclasses:
ViewHandlerWrapper
ViewHandler is the pluggablity mechanism for allowing implementations of or applications using the Jakarta Faces Specification to provide their own handling of the activities in the Render Response and Restore View phases of the request processing lifecycle. This allows for implementations to support different response generation technologies, as well as alternative strategies for saving and restoring the state of each view. An implementation of this class must be thread-safe.
Please see StateManager
for information on how the ViewHandler
interacts the
StateManager
.
Version 2 of the specification formally introduced the concept of View Declaration Language. A View
Declaration Language (VDL) is a syntax used to declare user interfaces comprised of instances of Jakarta Faces
UIComponent
s. Any of the responsibilities of the ViewHandler
that specifically deal with the VDL
sub-system are now the domain of the VDL implementation. These responsibilities are defined on the
ViewDeclarationLanguage
class. The ViewHandler
provides getViewDeclarationLanguage(jakarta.faces.context.FacesContext, java.lang.String)
as a
convenience method to access the VDL implementation given a viewId
.
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.static final String
The value to use for the default extension for Facelet based XHTML pages if the webapp is using url extension mapping.static final String
Deprecated, for removal: This API element is subject to removal in a future version.static final String
Deprecated, for removal: This API element is subject to removal in a future version.UseFACELETS_SUFFIX_PARAM_NAME
instead.static final String
The buffer size to set on the response when the ResponseWriter is generated.static final String
A semicolon (;) delimitted list of class names of type jakarta.faces.view.facelets.TagDecorator, with a no-argument constructor.static final String
If this param is set, the runtime must interpret it as a semicolon (;) separated list of paths, starting with "/" (without the quotes).static final String
When a page is requested, what interval in seconds should the compiler check for changes.static final String
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.static final String
Allow the web application to define a list of alternate suffixes for Facelet based XHTML pages containing Jakarta Faces content.static final String
Allow the web application to define a semicolon (;) separated list of strings that is used to forcibly declare that certain pages in the application must be interpreted as using Facelets, regardless of their extension. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addProtectedView
(String urlPattern) Add the argumenturlPattern
to the thread safeSet
of protected views for this application.calculateCharacterEncoding
(FacesContext context) Returns the correct character encoding to be used for this request.abstract Locale
calculateLocale
(FacesContext context) Returns an appropriateLocale
to use for this and subsequent requests for the current client.abstract String
calculateRenderKitId
(FacesContext context) Return an appropriaterenderKitId
for this and subsequent requests from the current client.abstract UIViewRoot
createView
(FacesContext context, String viewId) Create and return a newUIViewRoot
instance initialized with information from the argumentFacesContext
andviewId
.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.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.abstract String
getActionURL
(FacesContext context, String viewId) If the value returned from this method is used as thefile
argument to the four-argument constructor forjava.net.URL
(assuming appropriate values are used for the first three arguments), then a client making a request to thetoExternalForm()
of thatURL
will select the argumentviewId
for traversing the Jakarta Faces lifecycle.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.Return an unmodifiableSet
of the protected views currently known to thisViewHandler
instance.getRedirectURL
(FacesContext context, String viewId, Map<String, List<String>> parameters, boolean includeViewParams) Return a Jakarta Faces action URL derived from theviewId
argument that is suitable to be used by theNavigationHandler
to issue a redirect request to the URL using a NonFaces request.abstract String
getResourceURL
(FacesContext context, String path) If the value returned from this method is used as thefile
argument to the four-argument constructor forjava.net.URL
(assuming appropriate values are used for the first three arguments), then a client making a request to thetoExternalForm()
of thatURL
will select the argumentpath
for direct rendering.getViewDeclarationLanguage
(FacesContext context, String viewId) getViews
(FacesContext facesContext, String path, int maxDepth, ViewVisitOption... options) Return aStream
possibly lazily populated by walking the view trees of every activeViewDeclarationLanguage
rooted at a given initial path.getViews
(FacesContext facesContext, String path, ViewVisitOption... options) Return aStream
possibly lazily populated by walking the view trees of every activeViewDeclarationLanguage
rooted at a given initial path.abstract String
getWebsocketURL
(FacesContext context, String channel) If the value returned from this method is used as thefile
argument to the four-argument constructor forjava.net.URL
(assuming appropriate values are used for the first three arguments), then a client making a push handshake request to thetoExternalForm()
of thatURL
will select the argumentchannel
for connecting the websocket push channel in the current view.void
initView
(FacesContext context) Initialize the view for the request processing lifecycle.boolean
removeProtectedView
(String urlPattern) Remove the argumenturlPattern
from the thread safeSet
of protected views for this application, if present in theSet
.abstract void
renderView
(FacesContext context, UIViewRoot viewToRender) Perform whatever actions are required to render the response view to the response object associated with the currentFacesContext
.abstract UIViewRoot
restoreView
(FacesContext context, String viewId) Perform whatever actions are required to restore the view associated with the specifiedFacesContext
andviewId
.abstract void
writeState
(FacesContext context) Take any appropriate action to either immediately write out the current state information (by callingStateManager.writeState(jakarta.faces.context.FacesContext, java.lang.Object)
, or noting where state information should later be written.
-
Field Details
-
CHARACTER_ENCODING_KEY
The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.
- See Also:
-
DEFAULT_SUFFIX_PARAM_NAME
Deprecated, for removal: This API element is subject to removal in a future version.UseFACELETS_SUFFIX_PARAM_NAME
instead.This is not anymore used since removal of support for Jakarta Pages.
- See Also:
-
DEFAULT_SUFFIX
Deprecated, for removal: This API element is subject to removal in a future version.UseDEFAULT_FACELETS_SUFFIX
instead.This is not anymore used since removal of support for Jakarta Pages.
- See Also:
-
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
- See Also:
-
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 constantDEFAULT_FACELETS_SUFFIX
- Since:
- 2.0
- See Also:
-
DEFAULT_FACELETS_SUFFIX
The value to use for the default extension for Facelet based XHTML pages if the webapp is using url extension mapping.
- Since:
- 2.0
- See Also:
-
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
- See Also:
-
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
- See Also:
-
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
ProjectStage
. If it isProduction
, 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
- See Also:
-
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
- See Also:
-
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
- See Also:
-
-
Constructor Details
-
ViewHandler
public ViewHandler()
-
-
Method Details
-
initView
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()
returnsnull
, callcalculateCharacterEncoding(jakarta.faces.context.FacesContext)
and pass the result, if non-null
, into theExternalContext.setRequestCharacterEncoding(java.lang.String)
method. IfExternalContext.getRequestCharacterEncoding()
returns non-null
take no action.- Parameters:
context
- the Faces context.- Throws:
FacesException
- if a problem occurs setting the encoding, such as theUnsupportedEncodingException
thrown by the underlying Jakarta Servlet or Portlet technology when the encoding is not supported.
-
restoreView
Perform whatever actions are required to restore the view associated with the specified
FacesContext
andviewId
. It may delegate to therestoreView
of the associatedStateManager
to do the actual work of restoring the view. If there is no available state for the specifiedviewId
, returnnull
.Otherwise, the default implementation must obtain a reference to the
ViewDeclarationLanguage
for thisviewId
and call itsViewDeclarationLanguage.restoreView(jakarta.faces.context.FacesContext, java.lang.String)
method, returning the result and not swallowing any exceptions thrown by that method.- Parameters:
context
-FacesContext
for the current requestviewId
- the view identifier for the current request- Returns:
- the restored view root, or null.
- Throws:
NullPointerException
- ifcontext
isnull
FacesException
- if a Jakarta Servlet error occurs
-
createView
Create and return a new
UIViewRoot
instance initialized with information from the argumentFacesContext
andviewId
. Locate theViewDeclarationLanguage
implementation for the VDL used in the view. The argumentviewId
must be converted to a physicalviewId
that can refer to an actual resource suitable for use by theViewDeclarationLanguage
ViewDeclarationLanguage.createView(jakarta.faces.context.FacesContext, java.lang.String)
, which must be called by this method.- Parameters:
context
- the Faces context.viewId
- the view id.- Returns:
- the viewroot.
- Throws:
NullPointerException
- ifcontext
isnull
-
renderView
public abstract void renderView(FacesContext context, UIViewRoot viewToRender) throws IOException, FacesException Perform whatever actions are required to render the response view to the response object associated with the current
FacesContext
.Otherwise, the default implementation must obtain a reference to the
ViewDeclarationLanguage
for theviewId
of the argumentviewToRender
and call itsViewDeclarationLanguage.renderView(jakarta.faces.context.FacesContext, jakarta.faces.component.UIViewRoot)
method, returning the result and not swallowing any exceptions thrown by that method.- Parameters:
context
-FacesContext
for the current requestviewToRender
- the view to render- Throws:
IOException
- if an input/output error occursNullPointerException
- ifcontext
orviewToRender
isnull
FacesException
- if a Jakarta Servlet error occurs
-
calculateLocale
Returns an appropriate
Locale
to use for this and subsequent requests for the current client.- Parameters:
context
-FacesContext
for the current request- Returns:
- the locale.
- Throws:
NullPointerException
- ifcontext
isnull
-
calculateCharacterEncoding
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 acharset
parameter, extract it and return that as the encoding. -
If no
charset
parameter was found, check for the existence of a session by callingExternalContext.getSession(boolean)
passingfalse
as the argument. If that method returnstrue
, get the session Map by callingExternalContext.getSessionMap()
and look for a value under the key given by the value of the symbolic constantCHARACTER_ENCODING_KEY
. If present, return the value, converted to String. -
Otherwise, return
null
- Parameters:
context
- the Faces context.- Returns:
- the character encoding, or
null
- Since:
- 1.2
-
-
calculateRenderKitId
Return an appropriate
renderKitId
for this and subsequent requests from the current client. It is an error for this method to returnnull
.The default return value is
RenderKitFactory.HTML_BASIC_RENDER_KIT
.- Parameters:
context
-FacesContext
for the current request- Returns:
- the render kit id.
- Throws:
NullPointerException
- ifcontext
isnull
-
deriveViewId
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 anexact match
(mapping) as defined by Servlet.12.2. Note thatpath mapping
is also commonly known as prefix mapping (e.g. "/faces/*") andextension mapping
as suffix mapping (e.g. "*.xhtml"). Anexact 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
- theFacesContext
for this requestrequestViewId
- theviewId
to derive,- Returns:
- the derived view id.
- Since:
- 2.0
-
deriveLogicalViewId
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 anexact match
(mapping) as defined by Servlet.12.2. Note thatpath mapping
is also commonly known as prefix mapping (e.g. "/faces/*") andextension mapping
as suffix mapping (e.g. "*.xhtml"). Anexact 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
- theFacesContext
for this requestrequestViewId
- theviewId
to derive,- Returns:
- the derived logical view id.
- Since:
- 2.1
-
getActionURL
If the value returned from this method is used as the
file
argument to the four-argument constructor forjava.net.URL
(assuming appropriate values are used for the first three arguments), then a client making a request to thetoExternalForm()
of thatURL
will select the argumentviewId
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 theResponseStateManager.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
for this requestviewId
- View identifier of the desired view- Returns:
- the action url.
- Throws:
IllegalArgumentException
- ifviewId
is not valid for thisViewHandler
, or does not start with "/".NullPointerException
- ifcontext
orviewId
isnull
.
-
getRedirectURL
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 theNavigationHandler
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 togetActionURL(jakarta.faces.context.FacesContext, java.lang.String)
, passing the argumentscontext
andviewId
.- Parameters:
context
- The FacesContext processing this requestviewId
- The view identifier of the target pageparameters
- A mapping of parameter names to one or more valuesincludeViewParams
- A flag indicating whether view parameters should be encoded into this URL- Returns:
- the redirect URL.
- Since:
- 2.0
-
getBookmarkableURL
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(jakarta.faces.context.FacesContext, java.lang.String)
, passing the argumentscontext
andviewId
.- Parameters:
context
- The FacesContext processing this requestviewId
- The view identifier of the target pageparameters
- A mapping of parameter names to one or more valuesincludeViewParams
- A flag indicating whether view parameters should be encoded into this URL- Returns:
- the bookmarkable URL.
- Since:
- 2.0
-
getResourceURL
If the value returned from this method is used as the
file
argument to the four-argument constructor forjava.net.URL
(assuming appropriate values are used for the first three arguments), then a client making a request to thetoExternalForm()
of thatURL
will select the argumentpath
for direct rendering. If the specified path starts with a slash, it must be treated as context relative; otherwise, it must be treated as relative to the action URL of the current view.- Parameters:
context
-FacesContext
for the current requestpath
- Resource path to convert to a URL- Returns:
- the resource URL.
- Throws:
IllegalArgumentException
- ifviewId
is not valid for thisViewHandler
.NullPointerException
- ifcontext
orpath
isnull
.
-
getWebsocketURL
If the value returned from this method is used as the
file
argument to the four-argument constructor forjava.net.URL
(assuming appropriate values are used for the first three arguments), then a client making a push handshake request to thetoExternalForm()
of thatURL
will select the argumentchannel
for connecting the websocket push channel in the current view. It must match thePushContext.URI_PREFIX
of the endpoint.- Parameters:
context
-FacesContext
for the current request.channel
- The channel name of the websocket.- Returns:
- the websocket URL.
- Throws:
NullPointerException
- ifcontext
orchannel
isnull
.- See Also:
-
getProtectedViewsUnmodifiable
Return an unmodifiable
Set
of the protected views currently known to thisViewHandler
instance. Compliant implementations must return aSet
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 emptySet
.- Returns:
- the unmodifiable set of protected views.
- Since:
- 2.2
-
addProtectedView
Add the argument
urlPattern
to the thread safeSet
of protected views for this application. Compliant implementations make it so a subsequent call togetProtectedViewsUnmodifiable()
contains the argument. The runtime must support calling this method at any time after application startup. The default implementation takes no action.- Parameters:
urlPattern
- the url-pattern to add.- Since:
- 2.2
-
removeProtectedView
Remove the argument
urlPattern
from the thread safeSet
of protected views for this application, if present in theSet
. If the argumenturlPattern
is not present in theSet
, this method has no effect. Compliant implementations must make it so a subsequent call togetProtectedViewsUnmodifiable()
does not contain the argument. The runtime must support calling this method at any time after application startup. Returnstrue
if thisSet
contained the argument. The default implementation takes no action and returnsfalse
.- Parameters:
urlPattern
- the url-pattern to remove.- Returns:
true
if in theSet
,false
otherwise.- Since:
- 2.2
-
getViewDeclarationLanguage
Return the
ViewDeclarationLanguage
instance used for thisViewHandler
instance.The default implementation must use
ViewDeclarationLanguageFactory.getViewDeclarationLanguage(java.lang.String)
to obtain the appropriateViewDeclarationLanguage
implementation for the argumentviewId
. Any exceptions thrown as a result of invoking that method must not be swallowed.The default implementation of this method returns null.
- Parameters:
context
- theFacesContext
for this request.viewId
- the logical view id, as returned fromderiveLogicalViewId(jakarta.faces.context.FacesContext, java.lang.String)
for which theViewDeclarationLanguage
should be returned.- Returns:
- the ViewDeclarationLanguage, or null.
- Since:
- 2.0
-
getViews
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 activeViewDeclarationLanguage
rooted at a given initial path. The view tree of everyViewDeclarationLanguage
is individually traversed breadth-first as per the contract ofViewDeclarationLanguage.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 eachViewDeclarationLanguage
beyond the initial path, which is always visited. The value is relative to the root (/
), not to the given initial path. E.g. givenmaxDepth
=3
and initial path/foo/
, visiting will proceed up to/foo/bar/
, where/
counts as depth1
,/foo/
as depth2
and/foo/bar/
as depth3
. A value lower or equal to the depth of the initial path means that only the initial path is visited. A value ofMAX_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 eachViewDeclarationLanguage
appear in the stream is undetermined, except for the guarantee that every individualViewDeclarationLanguage
is traversed breadth-first.- Parameters:
facesContext
- TheFacesContext
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. SeeViewVisitOption
for details on those.- Returns:
- the
Stream
of view ids - Since:
- 2.3
-
getViews
Return a
Stream
possibly lazily populated by walking the view trees of every activeViewDeclarationLanguage
rooted at a given initial path. The view tree of everyViewDeclarationLanguage
is individually traversed breadth-first as per the contract ofViewDeclarationLanguage.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)
In case more than one active
ViewDeclarationLanguage
is present, the order in which view ids from eachViewDeclarationLanguage
appear in the stream is undetermined, except for the guarantee that every individualViewDeclarationLanguage
is traversed breadth-first.- Parameters:
facesContext
- TheFacesContext
for this request.path
- The initial path from which to start looking for view ids.options
- The options to influence the traversal. SeeViewVisitOption
for details on those.- Returns:
- the
Stream
of view ids - Since:
- 2.3
-
writeState
Take any appropriate action to either immediately write out the current state information (by calling
StateManager.writeState(jakarta.faces.context.FacesContext, java.lang.Object)
, or noting where state information should later be written.This method must do nothing if the current request is an
Ajax
request. When responding toAjax
requests, the state is obtained by callingStateManager.getViewState(jakarta.faces.context.FacesContext)
and then written into theAjax
response during final encoding (PartialViewContext.processPartial(jakarta.faces.event.PhaseId)
) .- Parameters:
context
-FacesContext
for the current request- Throws:
IOException
- if an input/output error occursNullPointerException
- ifcontext
isnull
-
DEFAULT_FACELETS_SUFFIX
instead.