|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjavax.faces.application.ViewHandler
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 Page Declaration Language. A Page
Declaration Language (PDL) is a syntax used to declare user
interfaces comprised of instances of JSF UIComponent
s. 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 |
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 |
void |
retargetMethodExpressions(FacesContext context,
UIComponent topLevelComponent)
Assuming the component metadata for
argument |
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 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 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 String DEFAULT_SUFFIX
The value to use for the default extension if the webapp is using url extension mapping.
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
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.
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.
Constructor Detail |
---|
public ViewHandler()
Method Detail |
---|
public abstract 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
NullPointerException
- if context
is
null
public 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 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
NullPointerException
- if context
is
null
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 PhaseListener
s 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.
NullPointerException
- if context
is null
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.
context
- FacesContext
for this requestviewId
- View identifier of the desired view
IllegalArgumentException
- if viewId
is not
valid for this ViewHandler
.
NullPointerException
- if context
or
viewId
is null
.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.
context
- FacesContext
for the current requestpath
- Resource path to convert to a URL
IllegalArgumentException
- if viewId
is not
valid for this ViewHandler
.
NullPointerException
- if context
or
path
is null
.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.
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 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.
context
- FacesContext
for the current requestviewToRender
- the view to render
IOException
- if an input/output error occurs
NullPointerException
- if context
or
viewToRender
is null
FacesException
- if a servlet error occurspublic 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.
context
- FacesContext
for the current requestviewId
- the view identifier for the current request
NullPointerException
- if context
is null
FacesException
- if a servlet error occurspublic 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.
Obtain the metadata for the composite component.
Currently this entails getting the value of the UIComponent.BEANINFO_KEY
component attribute, which will be
an instance of BeanInfo
. If the metadata cannot
be found, log an error message and return.
Get the BeanDescriptor
from the
BeanInfo
.
Get the value of the AttachedObjectTarget.ATTACHED_OBJECT_TARGETS_KEY
from the
BeanDescriptor
's getValue()
method.
This will be a List<
. Let this be
targetList.AttachedObjectTarget
>
For each curHandler entry in the argument
handlers
Let forAttributeValue be the return from
AttachedObjectHandler.getFor()
.
For each curTarget entry in targetList, the first of the following items that causes a match will take this action:
For each UIComponent
in the
list returned from curTarget.getTargets(), call
curHandler.applyAttachedObject(),
passing the FacesContext
and the
UIComponent
.
and cause this inner loop to terminate.
If curHandler is an instance of ActionSource2AttachedObjectHandler
and curTarget is
an instance of ActionSource2AttachedObjectTarget
,
consider it a match.
If curHandler is an instance of EditableValueHolderAttachedObjectHandler
and curTarget is
an instance of EditableValueHolderAttachedObjectTarget
,
consider it a match.
If curHandler is an instance of ValueHolderAttachedObjectHandler
and curTarget is
an instance of ValueHolderAttachedObjectTarget
,
consider it a match.
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.
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.
NullPointerException
- if any of the arguments are
null
.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.
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?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)
.
context
- FacesContext
for the current request
IOException
- if an input/output error occurs
NullPointerException
- if context
is null
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |