public abstract class ViewHandler
extends java.lang.Object
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
.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
CHARACTER_ENCODING_KEY
The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.
|
static java.lang.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. |
static java.lang.String |
DEFAULT_SUFFIX
Deprecated.
Use
DEFAULT_FACELETS_SUFFIX instead. |
static java.lang.String |
DEFAULT_SUFFIX_PARAM_NAME
Deprecated.
Use
FACELETS_SUFFIX_PARAM_NAME instead. |
static java.lang.String |
FACELETS_BUFFER_SIZE_PARAM_NAME
The buffer size to set on the response when the ResponseWriter is generated. |
static java.lang.String |
FACELETS_DECORATORS_PARAM_NAME
A semicolon (;) delimitted list of class names of type jakarta.faces.view.facelets.TagDecorator, with a no-argument constructor. |
static java.lang.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). |
static java.lang.String |
FACELETS_REFRESH_PERIOD_PARAM_NAME
When a page is requested, what interval in seconds should the compiler check for changes. |
static java.lang.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. |
static java.lang.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. |
static java.lang.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. |
Constructor and Description |
---|
ViewHandler() |
Modifier and Type | Method and Description |
---|---|
void |
addProtectedView(java.lang.String urlPattern)
Add the argument |
java.lang.String |
calculateCharacterEncoding(FacesContext context)
Returns the correct character encoding to be used for this request.
|
abstract java.util.Locale |
calculateLocale(FacesContext context)
Returns an appropriate
Locale to use for this and subsequent requests for the current client. |
abstract java.lang.String |
calculateRenderKitId(FacesContext context)
Return an appropriate
renderKitId for this and subsequent requests from the current client. |
abstract UIViewRoot |
createView(FacesContext context,
java.lang.String viewId)
Create and return a new
UIViewRoot instance initialized with
information from the argument FacesContext and viewId . |
java.lang.String |
deriveLogicalViewId(FacesContext context,
java.lang.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. |
java.lang.String |
deriveViewId(FacesContext context,
java.lang.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 java.lang.String |
getActionURL(FacesContext context,
java.lang.String viewId)
If the value returned from this method is used as the |
java.lang.String |
getBookmarkableURL(FacesContext context,
java.lang.String viewId,
java.util.Map<java.lang.String,java.util.List<java.lang.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. |
java.util.Set<java.lang.String> |
getProtectedViewsUnmodifiable()
Return an unmodifiable |
java.lang.String |
getRedirectURL(FacesContext context,
java.lang.String viewId,
java.util.Map<java.lang.String,java.util.List<java.lang.String>> parameters,
boolean includeViewParams)
Return a Jakarta Faces action URL derived from the |
abstract java.lang.String |
getResourceURL(FacesContext context,
java.lang.String path)
If the value returned from this method is used as the |
ViewDeclarationLanguage |
getViewDeclarationLanguage(FacesContext context,
java.lang.String viewId)
Return the |
java.util.stream.Stream<java.lang.String> |
getViews(FacesContext facesContext,
java.lang.String path,
int maxDepth,
ViewVisitOption... options)
Return a |
java.util.stream.Stream<java.lang.String> |
getViews(FacesContext facesContext,
java.lang.String path,
ViewVisitOption... options)
Return a |
abstract java.lang.String |
getWebsocketURL(FacesContext context,
java.lang.String channel)
If the value returned from this method is used as the |
void |
initView(FacesContext context)
Initialize the view for the request processing lifecycle.
|
boolean |
removeProtectedView(java.lang.String urlPattern)
Remove the argument |
abstract void |
renderView(FacesContext context,
UIViewRoot viewToRender)
Perform whatever actions are required to render the response view to the
response object associated with the current
FacesContext . |
abstract UIViewRoot |
restoreView(FacesContext context,
java.lang.String viewId)
Perform whatever actions are required to restore the view associated with
the specified
FacesContext and viewId . |
abstract void |
writeState(FacesContext context)
Take any appropriate action to either immediately write out the current state information (by calling
StateManager.writeState(jakarta.faces.context.FacesContext, java.lang.Object) , or noting where state information should later be written. |
public static final java.lang.String CHARACTER_ENCODING_KEY
The key, in the session's attribute set, under which the response character encoding may be stored and retrieved.
@Deprecated public static final java.lang.String DEFAULT_SUFFIX_PARAM_NAME
FACELETS_SUFFIX_PARAM_NAME
instead.This is not anymore used since removal of support for Jakarta Pages.
@Deprecated public static final java.lang.String DEFAULT_SUFFIX
DEFAULT_FACELETS_SUFFIX
instead.This is not anymore used since removal of support for Jakarta Pages.
public static final java.lang.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. The runtime must also consider the facelets.SKIP_COMMENTS param name as an alias to this param name for backwards compatibility with existing facelets tag libraries.
public static final java.lang.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
public static final java.lang.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 java.lang.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*
.
public static final java.lang.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. The runtime must also consider the facelets.BUFFER_SIZE param name as an alias to this param name for backwards compatibility with existing facelets tag libraries.
public static final java.lang.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.The
runtime must also consider the facelets.REFRESH_PERIOD param name as an alias to this param name for backwards
compatibility with existing facelets tag libraries. If
ProjectStage
is set to Production
and this value is not otherwise
specified, the runtime must act as if it is set to -1.
public static final java.lang.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". The runtime must also consider the facelets.LIBRARIES param name as an alias to this param name for backwards compatibility with existing facelets tag libraries.
public static final java.lang.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.The runtime must also consider the facelets.DECORATORS param name as an alias to this param name for backwards compatibility with existing facelets tag libraries.
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(jakarta.faces.context.FacesContext)
and pass the result, if non-null
,
into the ExternalContext.setRequestCharacterEncoding(java.lang.String)
method. If
ExternalContext.getRequestCharacterEncoding()
returns non-null
take no action.
context
- the Faces context.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 abstract UIViewRoot restoreView(FacesContext context, java.lang.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(jakarta.faces.context.FacesContext, java.lang.String)
method, returning the result and not
swallowing any exceptions thrown by that method.
context
- FacesContext
for the current requestviewId
- the view identifier for the current requestjava.lang.NullPointerException
- if context
is null
FacesException
- if a Jakarta Servlet error occurspublic abstract UIViewRoot createView(FacesContext context, java.lang.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(jakarta.faces.context.FacesContext, java.lang.String)
, which must be called by this method.
context
- the Faces context.viewId
- the view id.java.lang.NullPointerException
- if context
is null
public abstract void renderView(FacesContext context, UIViewRoot viewToRender) throws java.io.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(jakarta.faces.context.FacesContext, jakarta.faces.component.UIViewRoot)
method, returning the result and not swallowing any exceptions thrown by that method.
context
- FacesContext
for the current requestviewToRender
- the view to renderjava.io.IOException
- if an input/output error occursjava.lang.NullPointerException
- if context
or viewToRender
is null
FacesException
- if a Jakarta Servlet error occurspublic abstract java.util.Locale calculateLocale(FacesContext context)
Returns an appropriate Locale
to use for this and subsequent requests for the current client.
context
- FacesContext
for the current requestjava.lang.NullPointerException
- if context
is null
public java.lang.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 CHARACTER_ENCODING_KEY
. If present, return
the value, converted to String.
Otherwise, return null
context
- the Faces context.null
public abstract java.lang.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 RenderKitFactory.HTML_BASIC_RENDER_KIT
.
context
- FacesContext
for the current requestjava.lang.NullPointerException
- if context
is null
public java.lang.String deriveViewId(FacesContext context, java.lang.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.
context
- the FacesContext
for this requestrequestViewId
- the viewId
to derive,public java.lang.String deriveLogicalViewId(FacesContext context, java.lang.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.
context
- the FacesContext
for this requestrequestViewId
- the viewId
to derive,public abstract java.lang.String getActionURL(FacesContext context, java.lang.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 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.
context
- FacesContext
for this requestviewId
- View identifier of the desired viewjava.lang.IllegalArgumentException
- if viewId
is not valid for this ViewHandler
, or does not
start with "/".java.lang.NullPointerException
- if context
or viewId
is null
.public java.lang.String getRedirectURL(FacesContext context, java.lang.String viewId, java.util.Map<java.lang.String,java.util.List<java.lang.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(jakarta.faces.context.FacesContext, java.lang.String)
, passing the arguments context
and viewId
.
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 URLpublic java.lang.String getBookmarkableURL(FacesContext context, java.lang.String viewId, java.util.Map<java.lang.String,java.util.List<java.lang.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 arguments
context
and viewId
.
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 URLpublic abstract java.lang.String getResourceURL(FacesContext context, java.lang.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.
context
- FacesContext
for the current requestpath
- Resource path to convert to a URLjava.lang.IllegalArgumentException
- if viewId
is not valid for this ViewHandler
.java.lang.NullPointerException
- if context
or path
is null
.public abstract java.lang.String getWebsocketURL(FacesContext context, java.lang.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.
context
- FacesContext
for the current request.channel
- The channel name of the websocket.java.lang.NullPointerException
- if context
or channel
is null
.PushContext.URI_PREFIX
public java.util.Set<java.lang.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
.
public void addProtectedView(java.lang.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.
urlPattern
- the url-pattern to add.public boolean removeProtectedView(java.lang.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
.
urlPattern
- the url-pattern to remove.true
if in the Set
, false
otherwise.public ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context, java.lang.String viewId)
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.
context
- the FacesContext
for this request.viewId
- the logical view id, as returned from deriveLogicalViewId(jakarta.faces.context.FacesContext, java.lang.String)
for which the ViewDeclarationLanguage
should be returned.public java.util.stream.Stream<java.lang.String> getViews(FacesContext facesContext, java.lang.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.
facesContext
- 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.Stream
of view idspublic java.util.stream.Stream<java.lang.String> getViews(FacesContext facesContext, java.lang.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:
Put differently, it visits all levels of the view tree.getViews(facesContext, start, Integer.MAX_VALUE, options)
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.
facesContext
- 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.Stream
of view idspublic abstract void writeState(FacesContext context) throws java.io.IOException
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 to
Ajax
requests, the state is obtained by calling StateManager.getViewState(jakarta.faces.context.FacesContext)
and then written into
the Ajax
response during final encoding
(PartialViewContext.processPartial(jakarta.faces.event.PhaseId)
) .
context
- FacesContext
for the current requestjava.io.IOException
- if an input/output error occursjava.lang.NullPointerException
- if context
is null