javax.faces.application
Class ViewHandler

java.lang.Object
  extended by javax.faces.application.ViewHandler
Direct Known Subclasses:
ViewHandlerWrapper

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 Page Declaration Language. A Page Declaration Language (PDL) 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 PDL sub-system are now the domain of the PDL implementation. These responsibilities are defined on the PageDeclarationLanguage class. The ViewHandler provides getPageDeclarationLanguage(javax.faces.context.FacesContext, java.lang.String) as a convenience method to access the PDL implementation given a viewId.


Field Summary
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 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 Summary
ViewHandler()
           
 
Method Summary
 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.
abstract  String getActionURL(FacesContext context, String viewId)
          Return a URL suitable for rendering (after optional encoding performed by the encodeActionURL() method of ExternalContext) that selects the specified view identifier.
 PageDeclarationLanguage getPageDeclarationLanguage(FacesContext context, String viewId)
          

Return the PageDeclarationLanguage instance used for this ViewHandler instance.

abstract  String getResourceURL(FacesContext context, 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.
 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, String viewId)
          Perform whatever actions are required to restore the view associated with the specified FacesContext and viewId.
 void retargetAttachedObjects(FacesContext context, UIComponent topLevelComponent, List<AttachedObjectHandler> handlers)
          

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to PageDeclarationLanguage.getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting attached objects from the top level composite component to the individual AttachedObjectTarget instances inside the composite component.

 void retargetMethodExpressions(FacesContext context, UIComponent topLevelComponent)
          

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to PageDeclarationLanguage.getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting any method expressions from the top level component to the appropriate inner component.

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.
 
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 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 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 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 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 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 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 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:
NullPointerException - if context is null

calculateCharacterEncoding

public String calculateCharacterEncoding(FacesContext context)

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

The following algorithm is employed.

Since:
1.2

calculateRenderKitId

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.

Parameters:
context - FacesContext for the current request
Throws:
NullPointerException - if context is null

createView

public abstract UIViewRoot createView(FacesContext context,
                                      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.

If the view is written using Facelets, the markup comprising the view must be executed, with the UIComponent instances in the view being encountered in the same depth-first order as in other lifecycle methods defined on UIComponent, and added to the view (but not rendered) during the traversal. The runtime must guarantee that the view must be fully populated before the afterPhase() method of any PhaseListeners attached to the application or to the UIViewRoot (via UIViewRoot.setAfterPhaseListener(javax.el.MethodExpression) or UIViewRoot.addPhaseListener(javax.faces.event.PhaseListener)) are called. IMPORTANT: the new UIViewRoot instance must be passed to FacesContext.setViewRoot(javax.faces.component.UIViewRoot) before the execution of the Facelets view resulting in tree creation. This enables the broadest possible range of implementations for how tree creation is actually implemented.

Throws:
NullPointerException - if context is null

getActionURL

public abstract String getActionURL(FacesContext context,
                                    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:
IllegalArgumentException - if viewId is not valid for this ViewHandler.
NullPointerException - if context or viewId is null.

getResourceURL

public abstract String getResourceURL(FacesContext context,
                                      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:
IllegalArgumentException - if viewId is not valid for this ViewHandler.
NullPointerException - if context or path is null.

getPageDeclarationLanguage

public PageDeclarationLanguage getPageDeclarationLanguage(FacesContext context,
                                                          String viewId)

Return the PageDeclarationLanguage instance used for this ViewHandler instance.

The default implementation must use PageDeclarationLanguageFactory.getPageDeclarationLanguage(java.lang.String) to obtain the appropriate PageDeclarationLanguage implementation for the argument viewId. Any exceptions thrown as a result of invoking that method must not be swallowed.

An implementation is provided that will throw UnsupportedOperationException. A Faces implementation compliant with version 2.0 and beyond of the specification must override this method.

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(java.lang.String) 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 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 PageDeclarationLanguage for the viewId of the argument viewToRender and call its PageDeclarationLanguage.renderView(javax.faces.context.FacesContext, javax.faces.component.UIViewRoot) 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:
IOException - if an input/output error occurs
NullPointerException - if context or viewToRender is null
FacesException - if a servlet error occurs

restoreView

public 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 PageDeclarationLanguage for this viewId and call its PageDeclarationLanguage.restoreView(javax.faces.context.FacesContext, java.lang.String) 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:
NullPointerException - if context is null
FacesException - if a servlet error occurs

retargetAttachedObjects

public void retargetAttachedObjects(FacesContext context,
                                    UIComponent topLevelComponent,
                                    List<AttachedObjectHandler> handlers)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to PageDeclarationLanguage.getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting attached objects from the top level composite component to the individual AttachedObjectTarget instances inside the composite component. This method must be called by the PageDeclarationLanguage implementation when creating the UIComponent tree when a composite component usage is encountered.

An algorithm semantically equivalent to the following must be implemented.

An implementation is provided that will throw UnsupportedOperationException. A Faces implementation compliant with version 2.0 and beyond of the specification must override this method.

Parameters:
context - the FacesContext for this request.
topLevelComponent - The UIComponent in the view to which the attached objects must be attached. This UIComponent must have its component metadata already associated and available from via the JavaBeans API.
handlers - specified by the page author in the consuming page, provided to this method by the PDL implementation, this is a list of implementations of AttachedObjectHandler, each one of which represents a relationship between an attached object and the UIComponent to which it is attached.
Throws:
NullPointerException - if any of the arguments are null.
Since:
2.0

retargetMethodExpressions

public void retargetMethodExpressions(FacesContext context,
                                      UIComponent topLevelComponent)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to PageDeclarationLanguage.getComponentMetadata(javax.faces.context.FacesContext, javax.faces.application.Resource), leverage the component metadata for the purpose of re-targeting any method expressions from the top level component to the appropriate inner component. For each attribute that is a MethodExpression (as indicated by the presence of a "method-signature" attribute and the absence of a "type" attribute), the following action must be taken:

  • Get the value of the targets attribute. If the value is a ValueExpression evaluate it. If there is no targets attribute, let the name of the metadata element be the evaluated value of the targets attribute.

  • Interpret targets as a space (not tab) separated list of ids. For each entry in the list:

    • Find the inner component of the topLevelComponent with the id equal to the current list entry. For discussion, this component is called target. If not found, log and error and continue to the next attribute.

    • For discussion the declared name of the attribute is called name.

    • In the attributes map of the topLevelComponent, look up the entry under the key name. Assume the result is a ValueExpression. For discussion, this is attributeValueExpression. If not found, log an error and continue to the next attribute.

    • If name is equal to the string "action", or "actionListener" without the quotes, assume target is an ActionSource2.

    • If name is equal to the string "validator", or "valueChangeListener" without the quotes, assume target is an EditableValueHolder.

    • Call getExpressionString() on the attributeValueExpression and use that string to create a MethodExpression of the appropriate signature for name.

    • If name is not equal to any of the previously listed strings, call getExpressionString() on the attributeValueExpression and use that string to create a MethodExpression where the signature is created based on the value of the "method-signature" attribute of the <composite:attribute /> tag.

    • Let the resultant MethodExpression be called attributeMethodExpression for discussion.

    • If name is equal to the string "action" without the quotes, call ActionSource2.setActionExpression(javax.el.MethodExpression) on target, passing attributeMethodExpression.

    • If name is equal to the string "actionListener" without the quotes, call ActionSource.addActionListener(javax.faces.event.ActionListener) on target, passing attributeMethodExpression wrapped in a MethodExpressionActionListener.

    • If name is equal to the string "validator" without the quotes, call EditableValueHolder.addValidator(javax.faces.validator.Validator) on target, passing attributeMethodExpression wrapped in a MethodExpressionValidator.

    • If name is equal to the string "valueChangeListener" without the quotes, call EditableValueHolder.addValueChangeListener(javax.faces.event.ValueChangeListener) on target, passing attributeMethodExpression wrapped in a MethodExpressionValueChangeListener.

    • Otherwise, assume that the MethodExpression should be placed in the components attribute set. The runtme must create the MethodExpression instance based on the value of the "method-signature" attribute.

An implementation is provided that will throw UnsupportedOperationException. A Faces implementation compliant with version 2.0 and beyond of the specification must override this method.

Parameters:
context - the FacesContext for this request.
topLevelComponent - The UIComponent in the view to which the attached objects must be attached. This UIComponent must have its component metadata already associated and available from via the JavaBeans API. RELEASE_PENDING (edburns, rogerk) Exceptions for null arguments? If so, which ones?
Since:
2.0

writeState

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

Parameters:
context - FacesContext for the current request
Throws:
IOException - if an input/output error occurs
NullPointerException - if context is null


Copyright © 2002-2008 Sun Microsystems, Inc. All Rights Reserved.