javax.faces.application.ViewHandler
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public abstract class ViewHandler
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 |
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 |
abstract java.lang.String |
getResourceURL(FacesContext context,
java.lang.String path)
If the value returned from this
method is used as the |
ViewDeclarationLanguage |
getViewDeclarationLanguage(FacesContext context,
java.lang.String viewId)
Return
the |
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(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 |
|---|
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.
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.
public static final java.lang.String DEFAULT_SUFFIX
The value to use for the default extension if the webapp is using url extension mapping.
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
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.
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.
| Constructor Detail |
|---|
public ViewHandler()
| Method Detail |
|---|
public abstract java.util.Locale calculateLocale(FacesContext context)
Returns an appropriate Locale to use for this and
subsequent requests for the current client.
context - FacesContext for the current request
java.lang.NullPointerException - if context is
nullpublic 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
CHARACTER_ENCODING_KEY.
If present, return the value, converted to String.
Otherwise, return null
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.
context - FacesContext for the current request
java.lang.NullPointerException - if context is
null
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(javax.faces.context.FacesContext, java.lang.String), which must be called by
this method.
java.lang.NullPointerException - if context
is null
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.
context - the FacesContext for this requestrawViewId - the viewId to derive,
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.
context - the FacesContext for this requestrawViewId - the viewId to derive,
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.
context - FacesContext for this requestviewId - View identifier of the desired view
java.lang.IllegalArgumentException - if viewId is not
valid for this ViewHandler, or does not start with
"/".
java.lang.NullPointerException - if context or
viewId is null.
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.
context - FacesContext for the current requestpath - Resource path to convert to a URL
java.lang.IllegalArgumentException - if viewId is not
valid for this ViewHandler.
java.lang.NullPointerException - if context or
path is null.
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.
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 URL
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.
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 URL
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.
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 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(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 render
java.io.IOException - if an input/output error occurs
java.lang.NullPointerException - if context or
viewToRender is null
FacesException - if a servlet error occurs
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(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 request
java.lang.NullPointerException - if context
is null
FacesException - if a servlet error occurs
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(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 request
java.io.IOException - if an input/output error occurs
java.lang.NullPointerException - if context
is null
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||