public abstract Class ViewHandler

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

Parameters

urlPattern:String

the url-pattern to add.

Since

2.2

Returns the correct character encoding to be used for this request.

The following algorithm is employed.

• Examine the Content-Type request header. If it has a charset parameter, extract it and return that as the encoding.

• If no charset parameter was found, check for the existence of a session by calling ExternalContext#getSession(boolean) passing false as the argument. If that method returns true, get the session Map by calling ExternalContext#getSessionMap and look for a value under the key given by the value of the symbolic constant ViewHandler#CHARACTER_ENCODING_KEY. If present, return the value, converted to String.

• Otherwise, return null

Parameters

context:FacesContext

the Faces context.

Returns:String

the character encoding, or null

Since

1.2

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

Parameters

context:FacesContext

FacesContext for the current request

Returns:Locale

the locale.

Exceptions

NullPointerException:

if context is null

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

Parameters

context:FacesContext

FacesContext for the current request

Returns:String

the render kit id.

Exceptions

NullPointerException:

if context is null

Create and return a new UIViewRoot instance initialized with information from the argument FacesContext and viewId. Locate the ViewDeclarationLanguage implementation for the VDL used in the view. The argument viewId must be converted to a physical viewId that can refer to an actual resource suitable for use by the ViewDeclarationLanguage ViewDeclarationLanguage#createView, which must be called by this method.

Parameters

context:FacesContext

the Faces context.

viewId:String

the view id.

Returns:UIViewRoot

the viewroot.

Exceptions

NullPointerException:

if context is null

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.

This method should work correctly when the FacesServlet is invoked via either a path mapping, extension mapping or an exact match (mapping) as defined by Servlet.12.2. Note that path mapping is also commonly known as prefix mapping (e.g. "/faces/*") and extension mapping as suffix mapping (e.g. "*.xhtml"). An exact match is possible where there's a servlet mapping with an exact URL pattern such as "/foo".

The default implementation of this method simply returns requestViewId unchanged.

Parameters

context:FacesContext

the FacesContext for this request

requestViewId:String

the viewId to derive,

Returns:String

the derived logical view id.

Since

2.1

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.

This method should work correctly when the FacesServlet is invoked via either a path mapping, extension mapping or an exact match (mapping) as defined by Servlet.12.2. Note that path mapping is also commonly known as prefix mapping (e.g. "/faces/*") and extension mapping as suffix mapping (e.g. "*.xhtml"). An exact match is possible where there's a servlet mapping with an exact URL pattern such as "/foo".

The default implementation of this method simply returns requestViewId unchanged.

Parameters

context:FacesContext

the FacesContext for this request

requestViewId:String

the viewId to derive,

Returns:String

the derived view id.

Since

2.0

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 javax.faces.render.ResponseStateManager#NON_POSTBACK_VIEW_TOKEN_PARAM and the behavior when the current request is to a URL for which the FacesServlet has an exact mapping as defined by Servlet.12.2.

Parameters

context:FacesContext

FacesContext for this request

viewId:String

View identifier of the desired view

Returns:String

the action url.

Exceptions

IllegalArgumentException:

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

NullPointerException:

if context or viewId is null.

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

Parameters

context:FacesContext

The FacesContext processing this request

viewId:String

The view identifier of the target page

parameters:Map<String, List<String>>

A mapping of parameter names to one or more values

includeViewParams:boolean

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

Returns:String

the bookmarkable URL.

Since

2.0

Return an unmodifiable Set of the protected views currently known to this ViewHandler instance. Compliant implementations must return a Set that is the concatenation of the contents of all the <url-pattern> elements within all the <protected-views> in all of the application configuration resources in the current application. The runtime must support calling this method at any time after application startup. The default implementation returns an unmodifiable empty Set.

Returns:Set<String>

the unmodifiable set of protected views.

Since

2.2

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

Parameters

context:FacesContext

The FacesContext processing this request

viewId:String

The view identifier of the target page

parameters:Map<String, List<String>>

A mapping of parameter names to one or more values

includeViewParams:boolean

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

Returns:String

the redirect URL.

Since

2.0

If the value returned from this method is used as the file argument to the four-argument constructor for java.net.URL (assuming appropriate values are used for the first three arguments), then a client making a request to the toExternalForm() of that URL will select the argument path for direct rendering. If the specified path starts with a slash, it must be treated as context relative; otherwise, it must be treated as relative to the action URL of the current view.

Parameters

context:FacesContext

FacesContext for the current request

path:String

Resource path to convert to a URL

Returns:String

the resource URL.

Exceptions

IllegalArgumentException:

if viewId is not valid for this ViewHandler.

NullPointerException:

if context or path is null.

Return the ViewDeclarationLanguage instance used for this ViewHandler instance.

Parameters

context:FacesContext

the FacesContext for this request.

viewId:String

the logical view id, as returned from deriveLogicalViewId for which the ViewDeclarationLanguage should be returned.

Returns:ViewDeclarationLanguage

the ViewDeclarationLanguage, or null.

Since

2.0

Return a Stream possibly lazily populated by walking the view trees of every active ViewDeclarationLanguage rooted at a given initial path. The view tree of every ViewDeclarationLanguage is individually traversed breadth-first as per the contract of ViewDeclarationLanguage#getViews(FacesContext, String, int, ViewVisitOption...). The elements in the stream are logical view ids.

The maxDepth parameter is the maximum depth of directory levels to visit for each ViewDeclarationLanguage beyond the initial path, which is always visited. The value is relative to the root (/), not to the given initial path. E.g. given maxDepth = 3 and initial path /foo/, visiting will proceed up to /foo/bar/, where / counts as depth 1, /foo/ as depth 2 and /foo/bar/ as depth 3. A value lower or equal to the depth of the initial path means that only the initial path is visited. A value of MAX_VALUE may be used to indicate that all levels should be visited.

In case more than one active ViewDeclarationLanguage is present, the order in which view ids from each ViewDeclarationLanguage appear in the stream is undetermined, except for the guarantee that every individual ViewDeclarationLanguage is traversed breadth-first.

Parameters

facesContext:FacesContext

The FacesContext for this request.

path:String

The initial path from which to start looking for view ids.

maxDepth:int

The absolute maximum depth of nested directories to visit counted from the root (/).

options:ViewVisitOption[]

The options to influence the traversal. See ViewVisitOption for details on those.

Returns:Stream<String>

the Stream of view ids

Since

2.3

Return a Stream possibly lazily populated by walking the view trees of every active ViewDeclarationLanguage rooted at a given initial path. The view tree of every ViewDeclarationLanguage is individually traversed breadth-first as per the contract of ViewDeclarationLanguage#getViews(FacesContext, String, int, ViewVisitOption...). The elements in the stream are logical view ids.

This method works as if invoking it were equivalent to evaluating the expression:

getViews(facesContext, start, Integer.MAX_VALUE, options)

In case more than one active ViewDeclarationLanguage is present, the order in which view ids from each ViewDeclarationLanguage appear in the stream is undetermined, except for the guarantee that every individual ViewDeclarationLanguage is traversed breadth-first.

Parameters

facesContext:FacesContext

The FacesContext for this request.

path:String

The initial path from which to start looking for view ids.

options:ViewVisitOption[]

The options to influence the traversal. See ViewVisitOption for details on those.

Returns:Stream<String>

the Stream of view ids

Since

2.3

If the value returned from this method is used as the file argument to the four-argument constructor for java.net.URL (assuming appropriate values are used for the first three arguments), then a client making a push handshake request to the toExternalForm() of that URL will select the argument channel for connecting the websocket push channel in the current view. It must match the PushContext#URI_PREFIX of the endpoint.

Parameters

context:FacesContext

FacesContext for the current request.

channel:String

The channel name of the websocket.

Returns:String

the websocket URL.

Exceptions

NullPointerException:

if context or channel is null.

See Also

PushContext#URI_PREFIX

Initialize the view for the request processing lifecycle.

This method must be called at the beginning of the Restore View Phase of the Request Processing Lifecycle. It is responsible for performing any per-request initialization necessary to the operation of the lifycecle.

The default implementation must perform the following actions. If ExternalContext#getRequestCharacterEncoding returns null, call calculateCharacterEncoding and pass the result, if non-null, into the ExternalContext#setRequestCharacterEncoding method. If ExternalContext#getRequestCharacterEncoding returns non-null take no action.

Parameters

context:FacesContext

the Faces context.

Exceptions

FacesException:

if a problem occurs setting the encoding, such as the UnsupportedEncodingException thrown by the underlying Servlet or Portlet technology when the encoding is not supported.

Remove the argument urlPattern from the thread safe Set of protected views for this application, if present in the Set. If the argument urlPattern is not present in the Set, this method has no effect. Compliant implementations must make it so a subsequent call to getProtectedViewsUnmodifiable does not contain the argument. The runtime must support calling this method at any time after application startup. Returns true if this Set contained the argument. The default implementation takes no action and returns false.

Parameters

urlPattern:String

the url-pattern to remove.

Returns:boolean

true if in the Set, false otherwise.

Since

2.2

Perform whatever actions are required to render the response view to the response object associated with the current FacesContext.

Otherwise, the default implementation must obtain a reference to the ViewDeclarationLanguage for the viewId of the argument viewToRender and call its ViewDeclarationLanguage#renderView method, returning the result and not swallowing any exceptions thrown by that method.

Parameters

context:FacesContext

FacesContext for the current request

viewToRender:UIViewRoot

the view to render

Exceptions

IOException:

if an input/output error occurs

FacesException:

if a servlet error occurs

NullPointerException:

if context or viewToRender is null

Perform whatever actions are required to restore the view associated with the specified FacesContext and viewId. It may delegate to the restoreView of the associated StateManager to do the actual work of restoring the view. If there is no available state for the specified viewId, return null.

Otherwise, the default implementation must obtain a reference to the ViewDeclarationLanguage for this viewId and call its ViewDeclarationLanguage#restoreView method, returning the result and not swallowing any exceptions thrown by that method.

Parameters

context:FacesContext

FacesContext for the current request

viewId:String

the view identifier for the current request

Returns:UIViewRoot

the restored view root, or null.

Exceptions

NullPointerException:

if context is null

FacesException:

if a servlet error occurs

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 (javax.faces.context.PartialViewContext#processPartial(javax.faces.event.PhaseId)) .

Parameters

context:FacesContext

FacesContext for the current request

Exceptions

IOException:

if an input/output error occurs

NullPointerException:

if context is null