javax.faces.application
Class ViewHandler

java.lang.Object
  |
  +--javax.faces.application.ViewHandler

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.

Please see StateManager for information on how the ViewHandler interacts the StateManager.

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_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 an alternate suffix for pages containing JSF content.

Constructor Summary

ViewHandler()

Method Summary

abstract java.util.Locale	calculateLocale(javax.faces.context.FacesContext context) Returns an appropriate Locale to use for this and subsequent requests for the current client.
abstract java.lang.String	calculateRenderKitId(javax.faces.context.FacesContext context) Return an appropriate renderKitId for this and subsequent requests from the current client.
abstract javax.faces.component.UIViewRoot	createView(javax.faces.context.FacesContext context, java.lang.String viewId) Create and return a new UIViewRoot instance initialized with information from the argument FacesContext and viewId.
abstract java.lang.String	getActionURL(javax.faces.context.FacesContext context, java.lang.String viewId) Return a URL suitable for rendering (after optional encoding performed by the encodeActionURL() method of ExternalContext) that selects the specified view identifier.
abstract java.lang.String	getResourceURL(javax.faces.context.FacesContext context, java.lang.String path) Return a URL suitable for rendering (after optional encoding perfomed by the encodeResourceURL() method of ExternalContext) that selects the specifed web application resource.
abstract void	renderView(javax.faces.context.FacesContext context, javax.faces.component.UIViewRoot viewToRender) Perform whatever actions are required to render the response view to the response object associated with the current FacesContext.
abstract javax.faces.component.UIViewRoot	restoreView(javax.faces.context.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(javax.faces.context.FacesContext context) Take any appropriate action to either immediately write out the current state information (by calling StateManager.writeState(javax.faces.context.FacesContext, javax.faces.application.StateManager.SerializedView), 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 an alternate suffix for pages containing JSF content. 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

Constructor Detail

ViewHandler

public ViewHandler()

Method Detail

calculateLocale

public abstract java.util.Locale calculateLocale(javax.faces.context.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

calculateRenderKitId

public abstract java.lang.String calculateRenderKitId(javax.faces.context.FacesContext context)

Return an appropriate renderKitId for this and subsequent requests from the current client.

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 javax.faces.component.UIViewRoot createView(javax.faces.context.FacesContext context,
                                                            java.lang.String viewId)

Create and return a new UIViewRoot instance initialized with information from the argument FacesContext and viewId.

If there is an existing ViewRoot available on the FacesContext, this method must copy its locale and renderKitId to this new view root. If not, this method must call calculateLocale(javax.faces.context.FacesContext) and calculateRenderKitId(javax.faces.context.FacesContext), and store the results as the values of the locale and renderKitId, proeprties, respectively, of the newly created UIViewRoot.

Throws:

java.lang.NullPointerException - if context is null

getActionURL

public abstract java.lang.String getActionURL(javax.faces.context.FacesContext context,
                                              java.lang.String viewId)

Return a URL suitable for rendering (after optional encoding performed by the encodeActionURL() method of ExternalContext) that selects the specified view identifier.

Parameters:

context - FacesContext for this request

viewId - View identifier of the desired view

Throws:

java.lang.IllegalArgumentException - if viewId is not valid for this ViewHandler.

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

getResourceURL

public abstract java.lang.String getResourceURL(javax.faces.context.FacesContext context,
                                                java.lang.String path)

Return a URL suitable for rendering (after optional encoding perfomed by the encodeResourceURL() method of ExternalContext) that selects the specifed web application resource. 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:

java.lang.IllegalArgumentException - if viewId is not valid for this ViewHandler.

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

renderView

public abstract void renderView(javax.faces.context.FacesContext context,
                                javax.faces.component.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.

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 javax.faces.component.UIViewRoot restoreView(javax.faces.context.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.

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(javax.faces.context.FacesContext context)
                         throws java.io.IOException

Take any appropriate action to either immediately write out the current state information (by calling StateManager.writeState(javax.faces.context.FacesContext, javax.faces.application.StateManager.SerializedView), or noting where state information should later be written.

Parameters:

context - FacesContext for the current request

Throws:

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

java.lang.NullPointerException - if context is null