public abstract class ViewHandler extends Object
ViewHandler is the pluggablity mechanism for allowing implementations of or applications using the JavaServer 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 JSF 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(javax.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 String |
CHARACTER_ENCODING_KEY
The key, in the session's attribute set, under which the
response character encoding may be stored and retrieved.
|
static 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 String |
DEFAULT_SUFFIX
The value to use for the default extension if the webapp is using url extension mapping. |
static String |
DEFAULT_SUFFIX_PARAM_NAME
Allow the web
application to define a list
of alternate suffixes for pages containing JSF content.
|
static String |
DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME
If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the default ViewHandler must behave as specified in the latest 1.2 version of this specification. |
static String |
FACELETS_BUFFER_SIZE_PARAM_NAME
The buffer size to set on the response when the ResponseWriter is generated. |
static String |
FACELETS_DECORATORS_PARAM_NAME
A semicolon (;) delimitted list of class names of type javax.faces.view.facelets.TagDecorator, with a no-argument constructor. |
static 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 String |
FACELETS_REFRESH_PERIOD_PARAM_NAME
When a page is requested, what interval in seconds should the compiler check for changes. |
static 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 String |
FACELETS_SUFFIX_PARAM_NAME
Allow the web application to define an alternate suffix for Facelet based XHTML pages containing JSF content. |
static 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(String urlPattern)
Add the argument
|
String |
calculateCharacterEncoding(FacesContext context)
Returns the correct character encoding to be used for this request.
|
abstract Locale |
calculateLocale(FacesContext context)
Returns an appropriate
Locale to use for this and
subsequent requests for the current client. |
abstract String |
calculateRenderKitId(FacesContext context)
Return an appropriate
renderKitId for this and
subsequent requests from the current client. |
abstract UIViewRoot |
createView(FacesContext context,
String viewId)
Create and
return a new
UIViewRoot instance initialized with
information from the argument FacesContext and
viewId . |
String |
deriveLogicalViewId(FacesContext context,
String rawViewId)
Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2. |
String |
deriveViewId(FacesContext context,
String rawViewId)
Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2. |
abstract String |
getActionURL(FacesContext context,
String viewId)
If
the value returned from this
method is used as the |
String |
getBookmarkableURL(FacesContext context,
String viewId,
Map<String,List<String>> parameters,
boolean includeViewParams)
Return a JSF action URL derived from the viewId argument that is suitable to be used as the target of a link in a JSF response. |
Set<String> |
getProtectedViewsUnmodifiable()
Return an unmodifiable
|
String |
getRedirectURL(FacesContext context,
String viewId,
Map<String,List<String>> parameters,
boolean includeViewParams)
Return a JSF action URL derived
from the |
abstract String |
getResourceURL(FacesContext context,
String path)
If the value returned from this
method is used as the |
ViewDeclarationLanguage |
getViewDeclarationLanguage(FacesContext context,
String viewId)
Return
the |
void |
initView(FacesContext context)
Initialize the view
for the request processing lifecycle.
|
boolean |
removeProtectedView(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,
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(javax.faces.context.FacesContext, java.lang.Object) , or noting where state information
should later be written. |
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_SUFFIX_PARAM_NAME
Allow the web
application to define a list
of alternate suffixes for pages containing JSF 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_SUFFIX
.
public static final String DEFAULT_SUFFIX
The value to use for the default extension if the webapp is using url extension mapping.
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. 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 String FACELETS_SUFFIX_PARAM_NAME
Allow the web application to define an
alternate suffix for Facelet based XHTML pages containing JSF content.
If this init parameter is not specified, the default value is
taken from the value of the constant DEFAULT_FACELETS_SUFFIX
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 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.jsp*
. The runtime must also consider the
facelets.VIEW_MAPPINGS
param name as an alias to this
param name for backwards compatibility with existing Facelets
applications.
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. 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 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.
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". 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 String FACELETS_DECORATORS_PARAM_NAME
A semicolon (;) delimitted list of class names of type javax.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 static final String DISABLE_FACELET_JSF_VIEWHANDLER_PARAM_NAME
If this param is set, and calling toLowerCase().equals("true") on a String representation of its value returns true, the default ViewHandler must behave as specified in the latest 1.2 version of this specification. Any behavior specified in Section "Default ViewDeclarationLanguage Implementation" of the spec prose document and implemented in the default ViewHandler that pertains to handling requests for pages authored in the JavaServer Faces View Declaration Language must not be executed by the runtime.
public abstract Locale calculateLocale(FacesContext context)
Returns an appropriate Locale
to use for this and
subsequent requests for the current client.
context
- FacesContext
for the current requestNullPointerException
- if context
is
null
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
CHARACTER_ENCODING_KEY
.
If present, return the value, converted to String.
Otherwise, return 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 RenderKitFactory.HTML_BASIC_RENDER_KIT
.
context
- FacesContext
for the current requestNullPointerException
- 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(javax.faces.context.FacesContext, java.lang.String)
, which must be called by
this method.
NullPointerException
- if context
is null
public String deriveViewId(FacesContext context, String rawViewId)
Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.6.2.
The default implementation of this method simply returns rawViewId unchanged.
context
- the FacesContext
for this requestrawViewId
- the viewId
to derive,public String deriveLogicalViewId(FacesContext context, String rawViewId)
Derive and return the viewId from
the current request, or the argument input by following the
algorithm defined in specification section JSF.7.6.2. Note that
unlike deriveViewId()
, this method does not require that
a physical view be present.
The default implementation of this method simply returns rawViewId unchanged.
context
- the FacesContext
for this requestrawViewId
- the viewId
to derive,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 JSF lifecycle. Please see
section JSF.7.6.2 for the complete specification,
especially for details related
to view protection using the ResponseStateManager.NON_POSTBACK_VIEW_TOKEN_PARAM
.
context
- FacesContext
for this requestviewId
- View identifier of the desired viewIllegalArgumentException
- if viewId
is not
valid for this ViewHandler
, or does not start with
"/".NullPointerException
- if context
or
viewId
is null
.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.
context
- FacesContext
for the current requestpath
- Resource path to convert to a URLIllegalArgumentException
- if viewId
is not
valid for this ViewHandler
.NullPointerException
- if context
or
path
is null
.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
.
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.
urlPattern
- the url-pattern to add.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
.
urlPattern
- the url-pattern to remove.public String getRedirectURL(FacesContext context, String viewId, Map<String,List<String>> parameters, boolean includeViewParams)
Return a JSF action URL derived
from the viewId
argument that is suitable to be used
by the NavigationHandler
to issue a redirect request to
the URL using a NonFaces request. Compliant implementations
must implement this method as specified in section JSF.7.6.2.
The default implementation simply calls through to getActionURL(javax.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 String getBookmarkableURL(FacesContext context, String viewId, Map<String,List<String>> parameters, boolean includeViewParams)
Return a JSF action URL derived
from the viewId argument that is suitable to be used as the
target of a link in a JSF response. Compiliant implementations
must implement this method as specified in section JSF.7.6.2.
The default implementation simply calls through to getActionURL(javax.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 ViewDeclarationLanguage getViewDeclarationLanguage(FacesContext context, 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(javax.faces.context.FacesContext, java.lang.String)
for which the
ViewDeclarationLanguage
should be returned.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(javax.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.
FacesException
- if a problem occurs setting the encoding,
such as the UnsupportedEncodingException
thrown
by the underlying Servlet or Portlet technology when the encoding is not
supported.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(javax.faces.context.FacesContext, javax.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 renderIOException
- if an input/output error occursNullPointerException
- if context
or
viewToRender
is null
FacesException
- if a servlet error occurspublic 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(javax.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 requestNullPointerException
- if context
is null
FacesException
- if a servlet error occurspublic abstract void writeState(FacesContext context) throws IOException
Take any appropriate action to either immediately
write out the current state information (by calling
StateManager.writeState(javax.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(javax.faces.context.FacesContext)
and then written into the Ajax
response during final
encoding
(UIViewRoot.encodeEnd(javax.faces.context.FacesContext)
.
context
- FacesContext
for the current requestIOException
- if an input/output error occursNullPointerException
- if context
is null
Copyright © 2017 JBoss by Red Hat. All rights reserved.