public abstract class ViewDeclarationLanguage
extends java.lang.Object
The contract that a view declaration language must implement to interact with the Jakarta Faces runtime. An implementation of this class must be thread-safe.
Instances of this class are application scoped and must be obtained from the ViewDeclarationLanguageFactory
.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
FACELETS_VIEW_DECLARATION_LANGUAGE_ID
Identifier for the Facelets view declaration language. |
Constructor and Description |
---|
ViewDeclarationLanguage() |
Modifier and Type | Method and Description |
---|---|
abstract void |
buildView(FacesContext context,
UIViewRoot root)
Take any actions specific to this VDL implementation to cause the argument
|
java.util.List<java.lang.String> |
calculateResourceLibraryContracts(FacesContext context,
java.lang.String viewId)
Return the list of resource library contracts that will be made available for use in the view specified by the
argument |
UIComponent |
createComponent(FacesContext context,
java.lang.String taglibURI,
java.lang.String tagName,
java.util.Map<java.lang.String,java.lang.Object> attributes)
Create a component given a |
abstract UIViewRoot |
createView(FacesContext context,
java.lang.String viewId)
Create a |
abstract java.beans.BeanInfo |
getComponentMetadata(FacesContext context,
Resource componentResource)
Return a reference to the component metadata for the composite component represented by the argument
|
java.lang.String |
getId()
Returns a non-null String that can be used to identify this view declaration language. |
abstract Resource |
getScriptComponentResource(FacesContext context,
Resource componentResource)
Take implementation specific action to discover a |
abstract StateManagementStrategy |
getStateManagementStrategy(FacesContext context,
java.lang.String viewId)
For implementations that want to control the implementation of state saving and restoring, the
|
abstract ViewMetadata |
getViewMetadata(FacesContext context,
java.lang.String viewId)
Return a reference to the view metadata for the view represented by the argument |
java.util.stream.Stream<java.lang.String> |
getViews(FacesContext facesContext,
java.lang.String path,
int maxDepth,
ViewVisitOption... options)
Return a |
java.util.stream.Stream<java.lang.String> |
getViews(FacesContext facesContext,
java.lang.String path,
ViewVisitOption... options)
Return a |
abstract void |
renderView(FacesContext context,
UIViewRoot view)
Render a view rooted at argument |
abstract UIViewRoot |
restoreView(FacesContext context,
java.lang.String viewId)
Restore a |
void |
retargetAttachedObjects(FacesContext context,
UIComponent topLevelComponent,
java.util.List<AttachedObjectHandler> handlers)
Assuming the component metadata for argument
|
void |
retargetMethodExpressions(FacesContext context,
UIComponent topLevelComponent)
Assuming the component metadata for argument |
boolean |
viewExists(FacesContext context,
java.lang.String viewId)
Tests whether a physical resource corresponding to the specified viewId exists. |
public static final java.lang.String FACELETS_VIEW_DECLARATION_LANGUAGE_ID
Identifier for the Facelets view declaration language.
public abstract UIViewRoot restoreView(FacesContext context, java.lang.String viewId)
Restore a UIViewRoot
from a previously created view.
See section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document
for the specification of the default implementation.
context
- the FacesContext
for this request.viewId
- the identifier for a previously rendered view.java.lang.NullPointerException
- if any of the arguments are null
public abstract ViewMetadata getViewMetadata(FacesContext context, java.lang.String viewId)
Return a reference to the view metadata for the view represented by the argument viewId
, or
null
if the metadata cannot be found.
See section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document
for the specification of the default
implementation. Facelets implementation must return non-null
.
context
- The FacesContext
for this request.viewId
- the view id from which to extract the metadatajava.lang.NullPointerException
- if any of the arguments are null
.FacesException
- if there is an error in obtaining the metadatapublic abstract UIViewRoot createView(FacesContext context, java.lang.String viewId)
Create a UIViewRoot
from the VDL contained in the artifact
referenced by the argument viewId
.
See section 7.7.2"Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document
for the specification of the default implementation.
context
- the FacesContext
for this request.viewId
- the identifier of an artifact that contains the VDL syntax that describes this view.java.lang.NullPointerException
- if any of the arguments are null
public abstract void buildView(FacesContext context, UIViewRoot root) throws java.io.IOException
Take any actions specific to this VDL implementation to cause the argument
UIViewRoot
which must have been created via a call to createView(jakarta.faces.context.FacesContext, java.lang.String)
, to be populated with
children.
The Facelets implementation must insure that 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 any of the following happen.
The PhaseListener.afterPhase(jakarta.faces.event.PhaseEvent)
method of any PhaseListener
s attached to the
application is called
The UIViewRoot
phase listener installed via
UIViewRoot.setAfterPhaseListener(jakarta.el.MethodExpression)
or
UIViewRoot.addPhaseListener(jakarta.faces.event.PhaseListener)
are called.
If the root
is already populated with children, the view must still be re-built, but care must be taken
to ensure that the existing components are correctly paired up with their VDL counterparts in the VDL page. Also, any
system events that would normally be generated during the adding or removing of components from the view must be
temporarily disabled during the creation of the view and then re-enabled when the view has been built.
context
- the FacesContext
for this requestroot
- the UIViewRoot
to populate with children using techniques specific to this VDL
implementation.java.io.IOException
- if view cannot be built for any reasonpublic abstract void renderView(FacesContext context, UIViewRoot view) throws java.io.IOException
Render a view rooted at argumentview
.
See section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document
for the specification of the default implementation.
context
- the FacesContext
for this request.view
- the UIViewRoot
from an early call to createView(jakarta.faces.context.FacesContext, java.lang.String)
or restoreView(jakarta.faces.context.FacesContext, java.lang.String)
.java.lang.NullPointerException
- if any of the arguments are null
java.io.IOException
- if the view cannot be rendered for any reasonpublic abstract java.beans.BeanInfo getComponentMetadata(FacesContext context, Resource componentResource)
Return a reference to the component metadata for the composite component represented by the argument
componentResource
, or null
if the metadata cannot be found.
See section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document
for the specification of the default implementation. Jakarta Server Pages implementations must throw
UnsupportedOperationException
.
context
- The FacesContext
for this request.componentResource
- The Resource
that represents the component.java.lang.NullPointerException
- if any of the arguments are null
.FacesException
- if there is an error in obtaining the metadatajava.lang.UnsupportedOperationException
- if this is a Jakarta Server Pages VDL implementation.public abstract Resource getScriptComponentResource(FacesContext context, Resource componentResource)
Take implementation specific action to discover a Resource
given the argument
componentResource
.
See section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document
for the specification of the default implementation. Jakarta
Server Pages implementations must throw UnsupportedOperationException
.
context
- The FacesContext
for this request.componentResource
- The Resource
that represents the component.Resource
corresponding to the argument componentResource
java.lang.NullPointerException
- if any of the arguments are null
.FacesException
- if there is an error in obtaining the script component resourcejava.lang.UnsupportedOperationException
- if this is a Jakarta Server Pages VDL implementation.public UIComponent createComponent(FacesContext context, java.lang.String taglibURI, java.lang.String tagName, java.util.Map<java.lang.String,java.lang.Object> attributes)
Create a component given a ViewDeclarationLanguage
specific tag library URI and tag name. The runtime must
support this method operating for the Facelets VDL. Other kinds of ViewDeclarationLanguage
may be supported
but are not required to be supported. For backward compatibility with decorated ViewDeclrationLanguage
implementations that do not override this method, a default implementation is provided that returns null
.
However, any implementation that is compliant with the version of the specification in which this method was
introduced must implement this method.
context
- the FacesContext
for this requesttaglibURI
- the fully qualified tag library URI that contains the componenttagName
- the name of the tag within that library that exposes the componentattributes
- any name=value pairs that would otherwise have been given on the markup that would cause the
creation of this component or null
if no attributes need be given.java.lang.NullPointerException
- if context
, taglibURI
, or tagName
are null
public void retargetAttachedObjects(FacesContext context, UIComponent topLevelComponent, java.util.List<AttachedObjectHandler> handlers)
Assuming the component metadata for argument
topLevelComponent
has been made available by an earlier call to
getComponentMetadata(jakarta.faces.context.FacesContext, jakarta.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 ViewDeclarationLanguage
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
, and curTarget.getName() is equal to
curTargetName, consider it a match.
If curHandler is an instance of EditableValueHolderAttachedObjectHandler
and curTarget is
an instance of EditableValueHolderAttachedObjectTarget
, and
curTarget.getName() is equal to curTargetName, consider it a match.
If curHandler is an instance of ValueHolderAttachedObjectHandler
and curTarget is an
instance of ValueHolderAttachedObjectTarget
, and curTarget.getName() is equal to
curTargetName, consider it a match.
If curHandler is an instance of BehaviorHolderAttachedObjectHandler
and curTarget is an
instance of BehaviorHolderAttachedObjectTarget
, and either of the following conditions are true,
null
and is equal to curTargetName.null
and curTarget.isDefaultEvent() is
true
.consider it a match.
The implementation must support retargeting attached objects from the top level compsite component to targets that are composite and non-composite components.
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
- the tag handlers for the attached objectsjava.lang.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 getComponentMetadata(jakarta.faces.context.FacesContext, jakarta.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(jakarta.el.MethodExpression)
on target, passing
attributeMethodExpression.
If name is equal to the string "actionListener" without the quotes, call
ActionSource.addActionListener(jakarta.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(jakarta.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(jakarta.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.java.lang.NullPointerException
- if context
or topLevelComponent
is null
.public java.util.List<java.lang.String> calculateResourceLibraryContracts(FacesContext context, java.lang.String viewId)
Return the list of resource library contracts that will be made available for use in the view specified by the
argument viewId
. If no match is found, return an empty list.
See section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document for the specification of
the default implementation. For backward compatibility with prior implementations, an implementation is provided that
returns null
, but any implementation compliant with the version of the specification in which this method was
introduced must implement it as specified in
section 7.7.2 "Default ViewDeclarationLanguage Implementation" of the Jakarta Faces Specification Document.
context
- the FacesContext
for this requestviewId
- the view id for which the applicable resource library contracts should be calculated.public abstract StateManagementStrategy getStateManagementStrategy(FacesContext context, java.lang.String viewId)
For implementations that want to control the implementation of state saving and restoring, the
StateManagementStrategy
allows them to do so. Returning null
indicates that the implementation
wishes the runtime to handle the state saving and restoring. Implementations that provide the VDL for Facelets for
Jakarta Faces 2.0 and later must return non-null
from this method.
context
- the FacesContext
for the current request.viewId
- the view id.public boolean viewExists(FacesContext context, java.lang.String viewId)
Tests whether a physical resource corresponding to the specified viewId exists.
The default implementation uses ResourceHandler.createViewResource(jakarta.faces.context.FacesContext, java.lang.String)
to locate the
physical resource.
context
- The FacesContext
for this request.viewId
- the view id to testpublic java.util.stream.Stream<java.lang.String> getViews(FacesContext facesContext, java.lang.String path, ViewVisitOption... options)
Return a Stream
possibly lazily populated by walking the view tree rooted at a given initial path. The view
tree is traversed breadth-first, the elements in the stream are logical view ids.
This method works as if invoking it were equivalent to evaluating the expression:
Put differently, it visits all levels of the resource tree.getViewResources(facesContext, start, Integer.MAX_VALUE, options)
facesContext
- The FacesContext
for this request.path
- The initial path from which to start looking for viewsoptions
- The options to influence the traversal. See ViewVisitOption
for details on those.Stream
of view idspublic java.util.stream.Stream<java.lang.String> getViews(FacesContext facesContext, java.lang.String path, int maxDepth, ViewVisitOption... options)
Return a Stream
possibly lazily populated by walking the view tree rooted at a given initial path. The view
tree is traversed breadth-first, the elements in the stream are logical view ids.
The maxDepth
parameter is the maximum depth of directory levels to visit 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.
facesContext
- The FacesContext
for this request.path
- The initial path from which to start looking for viewsmaxDepth
- The absolute maximum depth of nested directories to visit counted from the root (/
).options
- The options to influence the traversal. See ViewVisitOption
for details on those.Stream
of view idspublic java.lang.String getId()
Returns a non-null String that can be used to identify this view declaration language.
The default implementation returns the fully qualified class name of the view declaration language implementation. Subclasses may override to provide a more meaningful id.