Module jakarta.faces

Package com.sun.faces.application.view

Class FaceletViewHandlingStrategy

java.lang.Object

jakarta.faces.view.ViewDeclarationLanguage

com.sun.faces.application.view.ViewHandlingStrategy

com.sun.faces.application.view.FaceletViewHandlingStrategy

public class FaceletViewHandlingStrategy
extends ViewHandlingStrategy

This ViewHandlingStrategy handles Facelets/PDL-based views.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected static final class	FaceletViewHandlingStrategy.NullWriter	Simple no-op writer.

Field Summary

Fields

Modifier and Type	Field	Description
static final String	IS_BUILDING_METADATA
static final String	RESOURCE_LIBRARY_CONTRACT_DATA_STRUCTURE_KEY

Fields inherited from class com.sun.faces.application.view.ViewHandlingStrategy

associate, webConfig

Fields inherited from class jakarta.faces.view.ViewDeclarationLanguage

FACELETS_VIEW_DECLARATION_LANGUAGE_ID

Constructor Summary

Constructors

Constructor	Description
FaceletViewHandlingStrategy()

Method Summary

Modifier and Type	Method	Description
void	buildView(FacesContext ctx, UIViewRoot view)	Take any actions specific to this VDL implementation to cause the argument UIViewRoot which must have been created via a call to ViewDeclarationLanguage.createView(jakarta.faces.context.FacesContext, java.lang.String), to be populated with children.
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.
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.
protected ResponseWriter	createResponseWriter(FacesContext context)
UIViewRoot	createView(FacesContext ctx, String viewId)	Create a UIViewRoot from the VDL contained in the artifact referenced by the argument viewId.
BeanInfo	getComponentMetadata(FacesContext context, Resource ccResource)	Called by Application._createComponent(Resource).
String	getId()	Returns a non-null String that can be used to identify this view declaration language.
protected String	getResponseContentType(FacesContext context, String orig)
protected String	getResponseEncoding(FacesContext context, String orig)
Resource	getScriptComponentResource(FacesContext context, Resource componentResource)	Take implementation specific action to discover a Resource given the argument componentResource.
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.
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.
Stream<String>	getViews(FacesContext context, String path, int maxDepth, ViewVisitOption... options)	Return a Stream possibly lazily populated by walking the view tree rooted at a given initial path.
Stream<String>	getViews(FacesContext context, String path, ViewVisitOption... options)	Return a Stream possibly lazily populated by walking the view tree rooted at a given initial path.
protected void	handleFaceletNotFound(FacesContext context, String viewId, String message)	Handles the case where a Facelet cannot be found.
protected void	handleRenderException(FacesContext context, Exception e)	Handles the case where rendering throws an Exception.
boolean	handlesViewId(String viewId)
protected void	initialize()	Initialize the core Facelets runtime.
protected void	initializeMappings()	Initialize mappings, during the first request.
static boolean	isBuildingMetadata(FacesContext context)
void	renderView(FacesContext ctx, UIViewRoot viewToRender)	Render a view rooted at argumentview.
UIViewRoot	restoreView(FacesContext context, String viewId)	If UIDebug.debugRequest(jakarta.faces.context.FacesContext)} is true, simply return a new UIViewRoot(), otherwise, call the default logic.
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(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.
void	retargetMethodExpressions(FacesContext context, UIComponent topLevelComponent)	Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to ViewDeclarationLanguage.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.
boolean	viewExists(FacesContext context, String viewId)	Tests whether a physical resource corresponding to the specified viewId exists.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Details

IS_BUILDING_METADATA

public static final String IS_BUILDING_METADATA

RESOURCE_LIBRARY_CONTRACT_DATA_STRUCTURE_KEY

public static final String RESOURCE_LIBRARY_CONTRACT_DATA_STRUCTURE_KEY

Constructor Details

FaceletViewHandlingStrategy

public FaceletViewHandlingStrategy()

Method Details

isBuildingMetadata

public static boolean isBuildingMetadata(FacesContext context)

restoreView

public UIViewRoot restoreView(FacesContext context,
 String viewId)

If UIDebug.debugRequest(jakarta.faces.context.FacesContext)} is true, simply return a new UIViewRoot(), otherwise, call the default logic.

Overrides:

restoreView in class ViewHandlingStrategy

Parameters:

context - the FacesContext for this request.

viewId - the identifier for a previously rendered view.

Returns:

the restored view

See Also:

• ViewDeclarationLanguage.restoreView(jakarta.faces.context.FacesContext, java.lang.String)

getViewMetadata

public ViewMetadata getViewMetadata(FacesContext context,
 String viewId)

Description copied from class: ViewDeclarationLanguage

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.

Specified by:

getViewMetadata in class ViewDeclarationLanguage

Parameters:

context - The FacesContext for this request.

viewId - the view id from which to extract the metadata

Returns:

the view metadata

createView

public UIViewRoot createView(FacesContext ctx,
 String viewId)

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

createView in class ViewHandlingStrategy

Parameters:

ctx - the FacesContext for this request.

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

Returns:

the newly created view root

See Also:

• ViewDeclarationLanguage.createView(jakarta.faces.context.FacesContext, String)

buildView

public void buildView(FacesContext ctx,
 UIViewRoot view)
               throws IOException

Description copied from class: ViewDeclarationLanguage

Take any actions specific to this VDL implementation to cause the argument UIViewRoot which must have been created via a call to ViewDeclarationLanguage.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 PhaseListeners 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.

Specified by:

buildView in class ViewDeclarationLanguage

Parameters:

ctx - the FacesContext for this request

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

Throws:

IOException - if view cannot be built for any reason

See Also:

• ViewDeclarationLanguage.buildView(FacesContext, UIViewRoot)

renderView

public void renderView(FacesContext ctx,
 UIViewRoot viewToRender)
                throws IOException

Description copied from class: ViewDeclarationLanguage

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.

Specified by:

renderView in class ViewDeclarationLanguage

Parameters:

ctx - the FacesContext for this request.

viewToRender - the UIViewRoot from an early call to ViewDeclarationLanguage.createView(jakarta.faces.context.FacesContext, java.lang.String) or ViewDeclarationLanguage.restoreView(jakarta.faces.context.FacesContext, java.lang.String).

Throws:

IOException - if the view cannot be rendered for any reason

See Also:

• ViewDeclarationLanguage.renderView(jakarta.faces.context.FacesContext, jakarta.faces.component.UIViewRoot)

getStateManagementStrategy

public StateManagementStrategy getStateManagementStrategy(FacesContext context,
 String viewId)

Description copied from class: ViewDeclarationLanguage

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.

Specified by:

getStateManagementStrategy in class ViewDeclarationLanguage

Parameters:

context - the FacesContext for the current request.

viewId - the view id.

Returns:

the strategy as specified above

getComponentMetadata

public BeanInfo getComponentMetadata(FacesContext context,
 Resource ccResource)

Called by Application._createComponent(Resource). This method creates two temporary UIComponent instances to aid in the creation of the compcomp metadata. These instances no longer needed after the method returns and can be safely garbage collected. PENDING(): memory analysis should be done to verify there are no memory leaks as a result of this implementation. The instances are 1. tmp: a jakarta.faces.NamingContainer to serve as the temporary top level component 2. facetComponent: a jakarta.faces.Panel to serve as the parent UIComponent that is passed to Facelets so that the <cc:interface> section can be parsed and understood. Per the compcomp spec, tmp has the compcomp Resource stored in its attr set under the key Resource.COMPONENT_RESOURCE_KEY. tmp has the facetComponent added as its UIComponent.COMPOSITE_FACET_NAME facet.

Specified by:

getComponentMetadata in class ViewDeclarationLanguage

Parameters:

context - The FacesContext for this request.

ccResource - The Resource that represents the component.

Returns:

the component metadata

getScriptComponentResource

public Resource getScriptComponentResource(FacesContext context,
 Resource componentResource)

Description copied from class: ViewDeclarationLanguage

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.

Specified by:

getScriptComponentResource in class ViewDeclarationLanguage

Parameters:

context - The FacesContext for this request.

componentResource - The Resource that represents the component.

Returns:

the Resource corresponding to the argument componentResource

See Also:

• ViewDeclarationLanguage.getScriptComponentResource(jakarta.faces.context.FacesContext, jakarta.faces.application.Resource)

retargetAttachedObjects

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

Description copied from class: ViewDeclarationLanguage

Assuming the component metadata for argument topLevelComponent has been made available by an earlier call to ViewDeclarationLanguage.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<AttachedObjectTarget>. Let this be targetList.

• 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 ActionSourceAttachedObjectHandler and curTarget is an instance of ActionSourceAttachedObjectTarget, 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,

      • curHandler.getEventName() is not null and is equal to curTargetName.
      • curHandler.getEventName() is 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.

Overrides:

retargetAttachedObjects in class ViewDeclarationLanguage

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 - the tag handlers for the attached objects

See Also:

• ViewDeclarationLanguage.retargetAttachedObjects(jakarta.faces.context.FacesContext, jakarta.faces.component.UIComponent, java.util.List)

retargetMethodExpressions

public void retargetMethodExpressions(FacesContext context,
 UIComponent topLevelComponent)

Description copied from class: ViewDeclarationLanguage

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

  • 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 ActionSource.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.

Overrides:

retargetMethodExpressions in class ViewDeclarationLanguage

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.

createComponent

public UIComponent createComponent(FacesContext context,
 String taglibURI,
 String tagName,
 Map<String,Object> attributes)

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

createComponent in class ViewDeclarationLanguage

Parameters:

context - the FacesContext for this request

taglibURI - the fully qualified tag library URI that contains the component

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

attributes - 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:

the newly created component

calculateResourceLibraryContracts

public List<String> calculateResourceLibraryContracts(FacesContext context,
 String viewId)

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

calculateResourceLibraryContracts in class ViewDeclarationLanguage

Parameters:

context - the FacesContext for this request

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

Returns:

the calculated list of resource library contract names

viewExists

public boolean viewExists(FacesContext context,
 String viewId)

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

viewExists in class ViewDeclarationLanguage

Parameters:

context - The FacesContext for this request.

viewId - the view id to test

Returns:

the result as specified above

getViews

public Stream<String> getViews(FacesContext context,
 String path,
 ViewVisitOption... options)

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

getViews in class ViewDeclarationLanguage

Parameters:

context - The FacesContext for this request.

path - The initial path from which to start looking for views

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

Returns:

the Stream of view ids

getViews

public Stream<String> getViews(FacesContext context,
 String path,
 int maxDepth,
 ViewVisitOption... options)

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

getViews in class ViewDeclarationLanguage

Parameters:

context - The FacesContext for this request.

path - The initial path from which to start looking for views

maxDepth - 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.

Returns:

the Stream of view ids

handlesViewId

public boolean handlesViewId(String viewId)

Specified by:

handlesViewId in class ViewHandlingStrategy

Parameters:

viewId - the view ID to check

Returns:

true if assuming a default configuration and the view ID's extension in ViewHandler.FACELETS_SUFFIX_PARAM_NAME Otherwise try to match the view ID based on the configured extensions and prefixes in ViewHandler.FACELETS_VIEW_MAPPINGS_PARAM_NAME

See Also:

• WebConfiguration.WebContextInitParameter.FaceletsSuffix
• WebConfiguration.WebContextInitParameter.FaceletsViewMappings

getId

public String getId()

Description copied from class: ViewDeclarationLanguage

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.

Overrides:

getId in class ViewDeclarationLanguage

Returns:

the id of this view declaration language

initialize

protected void initialize()

Initialize the core Facelets runtime.

initializeMappings

protected void initializeMappings()

Initialize mappings, during the first request.

createResponseWriter

protected ResponseWriter createResponseWriter(FacesContext context)
                                       throws IOException

Parameters:

context - the FacesContext for the current request

Returns:

a ResponseWriter for processing the request

Throws:

IOException - if the writer cannot be created

handleRenderException

protected void handleRenderException(FacesContext context,
 Exception e)
                              throws IOException

Handles the case where rendering throws an Exception.

Parameters:

context - the FacesContext for the current request

e - the caught Exception

Throws:

IOException - if the custom debug content cannot be written

handleFaceletNotFound

protected void handleFaceletNotFound(FacesContext context,
 String viewId,
 String message)
                              throws IOException

Handles the case where a Facelet cannot be found.

Parameters:

context - the FacesContext for the current request

viewId - the view ID that was to be mapped to a Facelet

message - optional message to include in the 404

Throws:

IOException - if an error occurs sending the 404 to the client

getResponseEncoding

protected String getResponseEncoding(FacesContext context,
 String orig)

Parameters:

context - the FacesContext for the current request

orig - the original encoding

Returns:

the encoding to be used for this response

getResponseContentType

protected String getResponseContentType(FacesContext context,
 String orig)

Parameters:

context - the FacesContext for the current request

orig - the original contentType

Returns:

the content type to be used for this response