javax.faces.application
Class ViewHandler

java.lang.Object
  javax.faces.application.ViewHandler

Direct Known Subclasses:

ViewHandlerWrapper

public abstract class ViewHandler
extends java.lang.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 UIComponents. 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.

Field Summary

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 The value to use for the default extension if the webapp is using url extension mapping.
static java.lang.String	DEFAULT_SUFFIX_PARAM_NAME Allow the web application to define a list of alternate suffixes for pages containing JSF content.
static java.lang.String	FACELETS_SUFFIX_PARAM_NAME Allow the web application to define an alternate suffix for Facelet based XHTML pages containing JSF 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 Summary

ViewHandler()

Method Summary

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 rawViewId) Derive and return the viewId from the current request, or the argument input by following the algorithm defined in specification section JSF.7.5.2.
java.lang.String	deriveViewId(FacesContext context, java.lang.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.5.2.
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 JSF lifecycle.
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 JSF action URL derived from the viewId argument that is suitable to be used as the target of a link in a JSF response.
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 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.
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.
ViewDeclarationLanguage	getViewDeclarationLanguage(FacesContext context, java.lang.String viewId) Return the ViewDeclarationLanguage instance used for this ViewHandler instance.
void	initView(FacesContext context) Initialize the view for the request processing lifecycle.
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, or noting where state information should later be written.

Methods inherited from class java.lang.Object

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

Field Detail

CHARACTER_ENCODING_KEY

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.

See Also:

Constant Field Values

DEFAULT_SUFFIX_PARAM_NAME

public static final java.lang.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.

See Also:

Constant Field Values

DEFAULT_SUFFIX

public static final java.lang.String DEFAULT_SUFFIX

The value to use for the default extension if the webapp is using url extension mapping.

See Also:

Constant Field Values

FACELETS_SUFFIX_PARAM_NAME

public static final java.lang.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

Since:

2.0

See Also:

Constant Field Values

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.

Since:

2.0

See Also:

Constant Field Values

FACELETS_VIEW_MAPPINGS_PARAM_NAME

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

Since:

2.0

See Also:

Constant Field Values

Constructor Detail

ViewHandler

public ViewHandler()

Method Detail

calculateLocale

public abstract java.util.Locale calculateLocale(FacesContext context)

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

Parameters:

context - FacesContext for the current request

Throws:

java.lang.NullPointerException - if context is null

calculateCharacterEncoding

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

• Otherwise, return null

Since:

1.2

calculateRenderKitId

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.

Parameters:

context - FacesContext for the current request

Throws:

java.lang.NullPointerException - if context is null

createView

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

Throws:

java.lang.NullPointerException - if context is null

deriveViewId

public java.lang.String deriveViewId(FacesContext context,
                                     java.lang.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.5.2.

The default implementation of this method simply returns rawViewId unchanged.

Parameters:

context - the FacesContext for this request

rawViewId - the viewId to derive,

Since:

2.0

deriveLogicalViewId

public java.lang.String deriveLogicalViewId(FacesContext context,
                                            java.lang.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.5.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.

Parameters:

context - the FacesContext for this request

rawViewId - the viewId to derive,

Since:

2.1

getActionURL

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 JSF lifecycle. Please see section JSF.7.5.2 for the complete specification.

Parameters:

context - FacesContext for this request

viewId - View identifier of the desired view

Throws:

IllegalArgumentException - if viewId is not valid for this ViewHandler, or does not start with "/".

java.lang.NullPointerException - if context or viewId is null.

getResourceURL

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

Parameters:

context - FacesContext for the current request

path - Resource path to convert to a URL

Throws:

IllegalArgumentException - if viewId is not valid for this ViewHandler.

java.lang.NullPointerException - if context or path is null.

getRedirectURL

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 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. Compiliant implementations must implement this method as specified in section JSF.7.5.2. The default implementation simply calls through to getActionURL(javax.faces.context.FacesContext, java.lang.String), passing the arguments context and viewId.

Parameters:

context - The FacesContext processing this request

viewId - The view identifier of the target page

parameters - A mapping of parameter names to one or more values

includeViewParams - A flag indicating whether view parameters should be encoded into this URL

Since:

2.0

getBookmarkableURL

public 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 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.5.2. The default implementation simply calls through to getActionURL(javax.faces.context.FacesContext, java.lang.String), passing the arguments context and viewId.

Parameters:

context - The FacesContext processing this request

viewId - The view identifier of the target page

parameters - A mapping of parameter names to one or more values

includeViewParams - A flag indicating whether view parameters should be encoded into this URL

Since:

2.0

getViewDeclarationLanguage

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.

Parameters:

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.

Since:

2.0

initView

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 method. If ExternalContext#getRequestCharacterEncoding returns non-null take no action.

Throws:

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.

renderView

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

Parameters:

context - FacesContext for the current request

viewToRender - the view to render

Throws:

java.io.IOException - if an input/output error occurs

java.lang.NullPointerException - if context or viewToRender is null

FacesException - if a servlet error occurs

restoreView

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

Parameters:

context - FacesContext for the current request

viewId - the view identifier for the current request

Throws:

java.lang.NullPointerException - if context is null

FacesException - if a servlet error occurs

writeState

public 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, 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 (UIViewRoot.encodeEnd(javax.faces.context.FacesContext).

Parameters:

context - FacesContext for the current request

Throws:

java.io.IOException - if an input/output error occurs

java.lang.NullPointerException - if context is null