Top Description Fields Constructors Methods
jakarta.faces.view

public abstract Class ViewDeclarationLanguage

extends Object
Class Inheritance
Known Direct Subclasses
jakarta.faces.view.ViewDeclarationLanguageWrapper
Static Imports
jakarta.faces.application.ResourceVisitOption.TOP_LEVEL_VIEWS_ONLY

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.

Since
2.0

Field Summary

Modifier and TypeField and Description
public static final String
FACELETS_VIEW_DECLARATION_LANGUAGE_ID

Identifier for the Facelets view declaration language.

Constructor Summary

AccessConstructor and Description
public
ViewDeclarationLanguage()

Method Summary

Modifier and TypeMethod and Description
public abstract void
buildView(FacesContext
the FacesContext for this request
context, UIViewRoot
the UIViewRoot to populate with children using techniques specific to this VDL implementation.
root)

Take any actions specific to this VDL implementation to cause the argument UIViewRoot which must have been created via a call to createView, to be populated with children.

public List<String>

Returns:

the calculated list of resource library contract names
calculateResourceLibraryContracts(FacesContext
the FacesContext for this request
context, String
the view id for which the applicable resource library contracts should be calculated.
viewId)

Return the list of resource library contracts that will be made available for use in the view specified by the argument viewId.

public UIComponent

Returns:

the newly created component
createComponent(FacesContext
the FacesContext for this request
context, String
the fully qualified tag library URI that contains the component
taglibURI, String
the name of the tag within that library that exposes the component
tagName, Map<String, Object>
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.
attributes)

Create a component given a ViewDeclarationLanguage specific tag library URI and tag name.

public abstract UIViewRoot

Returns:

the newly created view root
createView(FacesContext
the FacesContext for this request.
context, String
the identifier of an artifact that contains the VDL syntax that describes this view.
viewId)

Create a UIViewRoot from the VDL contained in the artifact referenced by the argument viewId.

public abstract BeanInfo

Returns:

the component metadata
getComponentMetadata(FacesContext
The FacesContext for this request.
context, Resource
The Resource that represents the component.
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.

public String

Returns:

the id of this view declaration language
getId()

Returns a non-null String that can be used to identify this view declaration language.

public abstract Resource

Returns:

the Resource corresponding to the argument componentResource
getScriptComponentResource(FacesContext
The FacesContext for this request.
context, Resource
The Resource that represents the component.
componentResource)

Take implementation specific action to discover a Resource given the argument componentResource.

public abstract StateManagementStrategy

Returns:

the strategy as specified above
getStateManagementStrategy(FacesContext
the FacesContext for the current request.
context, String
the view id.
viewId)

For implementations that want to control the implementation of state saving and restoring, the StateManagementStrategy allows them to do so.

public abstract ViewMetadata

Returns:

the view metadata
getViewMetadata(FacesContext
The FacesContext for this request.
context, String
the view id from which to extract the metadata
viewId)

Return a reference to the view metadata for the view represented by the argument viewId, or null if the metadata cannot be found.

public Stream<String>

Returns:

the Stream of view ids
getViews(FacesContext
The FacesContext for this request.
facesContext, String
The initial path from which to start looking for views
path, ViewVisitOption...
The options to influence the traversal. See ViewVisitOption for details on those.
options)

Return a Stream possibly lazily populated by walking the view tree rooted at a given initial path.

public Stream<String>

Returns:

the Stream of view ids
getViews(FacesContext
The FacesContext for this request.
facesContext, String
The initial path from which to start looking for views
path, int
The absolute maximum depth of nested directories to visit counted from the root (/).
maxDepth, ViewVisitOption...
The options to influence the traversal. See ViewVisitOption for details on those.
options)

Return a Stream possibly lazily populated by walking the view tree rooted at a given initial path.

public abstract void
renderView(FacesContext
the FacesContext for this request.
context, UIViewRoot
the UIViewRoot from an early call to createView or restoreView.
view)

Render a view rooted at argumentview.

public abstract UIViewRoot

Returns:

the restored view
restoreView(FacesContext
the FacesContext for this request.
context, String
the identifier for a previously rendered view.
viewId)

Restore a UIViewRoot from a previously created view.

public void
retargetAttachedObjects(FacesContext
the FacesContext for this request.
context, UIComponent
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.
topLevelComponent, List<AttachedObjectHandler>
the tag handlers for the attached objects
handlers)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to ViewDeclarationLanguage#getComponentMetadata, 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.

public void
retargetMethodExpressions(FacesContext
the FacesContext for this request.
context, UIComponent
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.
topLevelComponent)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to ViewDeclarationLanguage#getComponentMetadata, leverage the component metadata for the purpose of re-targeting any method expressions from the top level component to the appropriate inner component.

public boolean

Returns:

the result as specified above
viewExists(FacesContext
The FacesContext for this request.
context, String
the view id to test
viewId)

Tests whether a physical resource corresponding to the specified viewId exists.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

FACELETS_VIEW_DECLARATION_LANGUAGE_IDback to summary
public static final String FACELETS_VIEW_DECLARATION_LANGUAGE_ID

Identifier for the Facelets view declaration language.

Since
2.1

Constructor Detail

ViewDeclarationLanguageback to summary
public ViewDeclarationLanguage()

Method Detail

buildViewback to summary
public abstract void buildView(FacesContext context, UIViewRoot root) throws IOException

Take any actions specific to this VDL implementation to cause the argument UIViewRoot which must have been created via a call to createView, to be populated with children.

The Facelets implementation must insure that markup comprising the view must be executed, with the jakarta.faces.component.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.

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.

Parameters
context:FacesContext

the FacesContext for this request

root:UIViewRoot

the UIViewRoot to populate with children using techniques specific to this VDL implementation.

Exceptions
IOException:
if view cannot be built for any reason
calculateResourceLibraryContractsback to summary
public List<String> calculateResourceLibraryContracts(FacesContext context, 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.

Parameters
context:FacesContext

the FacesContext for this request

viewId:String

the view id for which the applicable resource library contracts should be calculated.

Returns:List<String>

the calculated list of resource library contract names

Since
2.2
createComponentback to summary
public UIComponent createComponent(FacesContext context, String taglibURI, String tagName, Map<String, 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.

Parameters
context:FacesContext

the FacesContext for this request

taglibURI:String

the fully qualified tag library URI that contains the component

tagName:String

the name of the tag within that library that exposes the component

attributes:Map<String, Object>

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.

Returns:UIComponent

the newly created component

Exceptions
NullPointerException:
if context, taglibURI, or tagName are null
Since
2.2
createViewback to summary
public abstract UIViewRoot createView(FacesContext context, 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.

Parameters
context:FacesContext

the FacesContext for this request.

viewId:String

the identifier of an artifact that contains the VDL syntax that describes this view.

Returns:UIViewRoot

the newly created view root

Exceptions
NullPointerException:
if any of the arguments are null
Since
2.0
getComponentMetadataback to summary
public abstract 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.

Parameters
context:FacesContext

The FacesContext for this request.

componentResource:Resource

The Resource that represents the component.

Returns:BeanInfo

the component metadata

Exceptions
NullPointerException:
if any of the arguments are null.
FacesException:
if there is an error in obtaining the metadata
UnsupportedOperationException:
if this is a Jakarta Server Pages VDL implementation.
Since
2.0
getIdback to summary
public 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.

Returns:String

the id of this view declaration language

Since
2.1
getScriptComponentResourceback to summary
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.

Parameters
context:FacesContext

The FacesContext for this request.

componentResource:Resource

The Resource that represents the component.

Returns:Resource

the Resource corresponding to the argument componentResource

Exceptions
NullPointerException:
if any of the arguments are null.
FacesException:
if there is an error in obtaining the script component resource
UnsupportedOperationException:
if this is a Jakarta Server Pages VDL implementation.
Since
2.0
getStateManagementStrategyback to summary
public abstract StateManagementStrategy getStateManagementStrategy(FacesContext context, 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.

Parameters
context:FacesContext

the FacesContext for the current request.

viewId:String

the view id.

Returns:StateManagementStrategy

the strategy as specified above

Since
2.0
getViewMetadataback to summary
public abstract ViewMetadata getViewMetadata(FacesContext context, 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.

Parameters
context:FacesContext

The FacesContext for this request.

viewId:String

the view id from which to extract the metadata

Returns:ViewMetadata

the view metadata

Exceptions
NullPointerException:
if any of the arguments are null.
FacesException:
if there is an error in obtaining the metadata
Since
2.0
getViewsback to summary
public Stream<String> getViews(FacesContext facesContext, 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: 

getViewResources(facesContext, start, Integer.MAX_VALUE, options)
Put differently, it visits all levels of the resource tree.
Parameters
facesContext:FacesContext

The FacesContext for this request.

path:String

The initial path from which to start looking for views

options:ViewVisitOption[]

The options to influence the traversal. See ViewVisitOption for details on those.

Returns:Stream<String>

the Stream of view ids

Since
2.3
getViewsback to summary
public Stream<String> getViews(FacesContext facesContext, 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.

Parameters
facesContext:FacesContext

The FacesContext for this request.

path:String

The initial path from which to start looking for views

maxDepth:int

The absolute maximum depth of nested directories to visit counted from the root (/).

options:ViewVisitOption[]

The options to influence the traversal. See ViewVisitOption for details on those.

Returns:Stream<String>

the Stream of view ids

Since
2.3
renderViewback to summary
public abstract void renderView(FacesContext context, UIViewRoot view) throws 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.

Parameters
context:FacesContext

the FacesContext for this request.

view:UIViewRoot

the UIViewRoot from an early call to createView or restoreView.

Exceptions
IOException:
if the view cannot be rendered for any reason
NullPointerException:
if any of the arguments are null
restoreViewback to summary
public abstract UIViewRoot restoreView(FacesContext context, 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.

Parameters
context:FacesContext

the FacesContext for this request.

viewId:String

the identifier for a previously rendered view.

Returns:UIViewRoot

the restored view

Exceptions
NullPointerException:
if any of the arguments are null
retargetAttachedObjectsback to summary
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 ViewDeclarationLanguage#getComponentMetadata, 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.

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.

Parameters
context:FacesContext

the FacesContext for this request.

topLevelComponent:UIComponent

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:List<AttachedObjectHandler>

the tag handlers for the attached objects

Exceptions
NullPointerException:
if any of the arguments are null.
Since
2.0
retargetMethodExpressionsback to summary
public void retargetMethodExpressions(FacesContext context, UIComponent topLevelComponent)

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to ViewDeclarationLanguage#getComponentMetadata, 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 jakarta.faces.component.ActionSource2.

    • If name is equal to the string "validator", or "valueChangeListener" without the quotes, assume target is an jakarta.faces.component.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 jakarta.faces.component.ActionSource2#setActionExpression on target, passing attributeMethodExpression.

    • If name is equal to the string "actionListener" without the quotes, call jakarta.faces.component.ActionSource#addActionListener on target, passing attributeMethodExpression wrapped in a jakarta.faces.event.MethodExpressionActionListener.

    • If name is equal to the string "validator" without the quotes, call jakarta.faces.component.EditableValueHolder#addValidator on target, passing attributeMethodExpression wrapped in a jakarta.faces.validator.MethodExpressionValidator.

    • If name is equal to the string "valueChangeListener" without the quotes, call jakarta.faces.component.EditableValueHolder#addValueChangeListener on target, passing attributeMethodExpression wrapped in a jakarta.faces.event.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:FacesContext

the FacesContext for this request.

topLevelComponent:UIComponent

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.

Exceptions
NullPointerException:
if context or topLevelComponent is null.
Since
2.0
viewExistsback to summary
public boolean viewExists(FacesContext context, String viewId)

Tests whether a physical resource corresponding to the specified viewId exists.

The default implementation uses jakarta.faces.application.ResourceHandler#createViewResource to locate the physical resource.

Parameters
context:FacesContext

The FacesContext for this request.

viewId:String

the view id to test

Returns:boolean

the result as specified above

Since
2.1