Module jakarta.faces

Package com.sun.faces.application.resource

Class ResourceHandlerImpl

java.lang.Object

jakarta.faces.application.ResourceHandler

com.sun.faces.application.resource.ResourceHandlerImpl

public class ResourceHandlerImpl
extends ResourceHandler

This is the default implementation of ResourceHandler.

Field Summary

Fields inherited from class jakarta.faces.application.ResourceHandler

FACES_SCRIPT_LIBRARY_NAME, FACES_SCRIPT_RESOURCE_NAME, JSF_SCRIPT_LIBRARY_NAME, JSF_SCRIPT_RESOURCE_NAME, LOCALE_PREFIX, RESOURCE_CONTRACT_XML, RESOURCE_EXCLUDES_DEFAULT_VALUE, RESOURCE_EXCLUDES_PARAM_NAME, RESOURCE_IDENTIFIER, WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME, WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME

Constructor Summary

Constructors

Constructor	Description
ResourceHandlerImpl()	Creates a new instance of ResourceHandlerImpl

Method Summary

Modifier and Type	Method	Description
Resource	createResource(String resourceName)	Create an instance of ViewResource given the argument resourceName.
Resource	createResource(String resourceName, String libraryName)	Create an instance of Resource with a resourceName given by the value of the argument resourceName that is a member of the library named by the argument libraryName.
Resource	createResource(String resourceName, String libraryName, String contentType)	Create an instance of Resource with a resourceName given by the value of the argument resourceName that is a member of the library named by the argument libraryName that claims to have the content-type given by the argument content-type.
Resource	createResourceFromId(String resourceId)	Create an instance of Resource given the argument resourceId.
Resource	createViewResource(FacesContext facesContext, String resourceName)	Create an instance of Resource given the argument resourceName, which may contain "/" characters.
String	getRendererTypeForResourceName(String resourceName)	Return the renderer-type for a Renderer that is capable of rendering this resource.
Stream<String>	getViewResources(FacesContext facesContext, String path, int maxDepth, ResourceVisitOption... options)	Return a Stream possibly lazily populated by walking the resource tree rooted at a given initial path.
Stream<String>	getViewResources(FacesContext facesContext, String path, ResourceVisitOption... options)	Return a Stream possibly lazily populated by walking the resource tree rooted at a given initial path.
void	handleResourceRequest(FacesContext context)	This method specifies the contract for satisfying resource requests.
boolean	isResourceRequest(FacesContext context)	Return true if the current request is a resource request.
boolean	libraryExists(String libraryName)	Return true if the resource library named by the argument libraryName can be found.

Methods inherited from class jakarta.faces.application.ResourceHandler

isResourceRendered, isResourceURL, markResourceRendered

Methods inherited from class java.lang.Object

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

Constructor Details

ResourceHandlerImpl

public ResourceHandlerImpl()

Creates a new instance of ResourceHandlerImpl

Method Details

createResource

public Resource createResource(String resourceName)

Description copied from class: ResourceHandler

Create an instance of ViewResource given the argument resourceName. The content-type of the resource is derived by passing the resourceName to ExternalContext.getMimeType(java.lang.String)

The algorithm specified in section 2.6.1.4 "Libraries of Localized and Versioned Resources" of the Jakarta Faces Specification Document must be executed to create the Resource. New requirements were introduced in version 2.2 of the specification. For historical reasons, this method operate correctly when the argument resourceName is of the form libraryName/resourceName, even when resourceName contains '/' characters.

Specified by:

createResource in class ResourceHandler

Parameters:

resourceName - the name of the resource.

Returns:

a newly created Resource instance, suitable for use in encoding or decoding the named resource.

See Also:

• ResourceHandler.createResource(String)

createResource

public Resource createResource(String resourceName,
 String libraryName)

Description copied from class: ResourceHandler

Create an instance of Resource with a resourceName given by the value of the argument resourceName that is a member of the library named by the argument libraryName. The content-type of the resource is derived by passing the resourceName to ExternalContext.getMimeType(java.lang.String).

The algorithm specified in section 2.6.1.4 "Libraries of Localized and Versioned Resources" of the Jakarta Faces Specification Document must be executed to create the Resource. New requirements were introduced in version 2.2 of the specification.

Specified by:

createResource in class ResourceHandler

Parameters:

resourceName - the name of the resource.

libraryName - the name of the library (or contract) in which this resource resides, may be null. If there is a conflict between the name of a resource library and a resource library contract, the resource library takes precedence. May not include relative paths, such as "../".

Returns:

a newly created Resource instance, suitable for use in encoding or decoding the named resource.

See Also:

• ResourceHandler.createResource(String, String)

createResource

public Resource createResource(String resourceName,
 String libraryName,
 String contentType)

Description copied from class: ResourceHandler

Create an instance of Resource with a resourceName given by the value of the argument resourceName that is a member of the library named by the argument libraryName that claims to have the content-type given by the argument content-type.

The algorithm specified in section 2.6.1.4 "Libraries of Localized and Versioned Resources" of the Jakarta Faces Specification Document must be executed to create the Resource. New requirements were introduced in version 2.2 of the specification.

Specified by:

createResource in class ResourceHandler

Parameters:

resourceName - the name of the resource.

libraryName - the name of the library in which this resource resides, may be null. May not include relative paths, such as "../".

contentType - the mime content that this Resource instance will return from Resource.getContentType(). If the value is null, The content-type of the resource is derived by passing the resourceName to ExternalContext.getMimeType(java.lang.String)

Returns:

a newly created Resource instance, suitable for use in encoding or decoding the named resource.

See Also:

• ResourceHandler.createResource(String, String, String)

createViewResource

public Resource createViewResource(FacesContext facesContext,
 String resourceName)

Description copied from class: ResourceHandler

Create an instance of Resource given the argument resourceName, which may contain "/" characters. The ViewDeclarationLanguage calls this method when it needs to load a view from a persistent store, such as a filesystem. This method is functionality equivalent to ResourceHandler.createResource(java.lang.String), but all callsites that need to load VDL views must use this method so that classes that want to decorate the ResourceHandler in order to only affect the loading of views may do so without affecting the processing of other kinds of resources, such as scripts and stylesheets. A FacesContext must be present before calling this method. To preserve compatibility with prior revisions of the specification, a default implementation must be provided that calls ResourceHandler.createResource(java.lang.String).

The default implementation must look for the resource in the following places, in this order.

• Considering resource library contracts (at the locations specified in the Jakarta Faces Specification Document section 2.7 "Resource Library Contracts").

• Considering the web app root.

• Considering faces flows (at the locations specified in the Jakarta Faces Specification Document section 11.3.3 "Faces Flows").

Call FacesContext.getResourceLibraryContracts(). If the result is non-null and not empty, for each value in the list, treat the value as the name of a resource library contract. If the argument resoureName exists as a resource in the resource library contract, return it. Otherwise, return the resource (not in the resource library contract), if found. Otherwise, return null.

Overrides:

createViewResource in class ResourceHandler

Parameters:

facesContext - the FacesContext for this request.

resourceName - the name of the resource to be interpreted as a view by the ViewDeclarationLanguage.

Returns:

a newly created ViewResource instance, suitable for use by the ViewDeclarationLanguage.

getViewResources

public Stream<String> getViewResources(FacesContext facesContext,
 String path,
 ResourceVisitOption... options)

Description copied from class: ResourceHandler

Return a Stream possibly lazily populated by walking the resource tree rooted at a given initial path. The resource tree is traversed breadth-first, the elements in the stream are view resource names that would yield a ViewResource when passed into ResourceHandler.createViewResource(jakarta.faces.context.FacesContext, java.lang.String) as the resourceName parameter.

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:

getViewResources in class ResourceHandler

Parameters:

facesContext - The FacesContext for this request.

path - The initial path from which to start looking for view resources

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

Returns:

the Stream of view resource names

See Also:

• ResourceHandler.getViewResources(FacesContext, String, ResourceVisitOption...)

getViewResources

public Stream<String> getViewResources(FacesContext facesContext,
 String path,
 int maxDepth,
 ResourceVisitOption... options)

Description copied from class: ResourceHandler

Return a Stream possibly lazily populated by walking the resource tree rooted at a given initial path. The resource tree is traversed breadth-first, the elements in the stream are view resource names that would yield a ViewResource when passed into ResourceHandler.createViewResource(jakarta.faces.context.FacesContext, java.lang.String) as the resourceName parameter.

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:

getViewResources in class ResourceHandler

Parameters:

facesContext - The FacesContext for this request.

path - The initial path from which to start looking for view resources

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

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

Returns:

the Stream of view resource names

See Also:

• ResourceHandler.getViewResources(FacesContext, String, int, ResourceVisitOption...)

createResourceFromId

public Resource createResourceFromId(String resourceId)

Description copied from class: ResourceHandler

Create an instance of Resource given the argument resourceId. The content-type of the resource is derived by passing the resourceName to ExternalContext.getMimeType(java.lang.String)

The resource must be identified according to the specification in section 2.6.1.3 "Resource Identifiers" of the Jakarta Faces Specification Document. New requirements were introduced in version 2.2 of the specification.

Overrides:

createResourceFromId in class ResourceHandler

Parameters:

resourceId - the resource identifier of the resource.

Returns:

a newly created Resource instance, suitable for use in encoding or decoding the named resource.

See Also:

• ResourceHandler.createResourceFromId(String)

libraryExists

public boolean libraryExists(String libraryName)

Description copied from class: ResourceHandler

Return true if the resource library named by the argument libraryName can be found. If there is a localePrefix for this application, as defined in ResourceHandler.LOCALE_PREFIX, first look for the library with the prefix. If no such library is found, look for the library without the prefix. This allows developers to avoid duplication of files. For example, consider the case where the developer wants to have a resource library containing a localized image resource and a non-localized script resource. By checking both locations for the existence of the library, along with other spec changes in section 2.6.1.4 "Libraries of Localized and Versioned Resources" of the Jakarta Faces Specification Document, this scenario is enabled.

Specified by:

libraryExists in class ResourceHandler

Parameters:

libraryName - the library name.

Returns:

true if the library exists, false otherwise.

isResourceRequest

public boolean isResourceRequest(FacesContext context)

Description copied from class: ResourceHandler

Return true if the current request is a resource request. This method is called by FacesServlet.service(jakarta.servlet.ServletRequest, jakarta.servlet.ServletResponse) to determine if this request is a view request or a resource request.

Specified by:

isResourceRequest in class ResourceHandler

Parameters:

context - the FacesContext for this request

Returns:

true if the current request is a resource request, false otherwise.

See Also:

• ResourceHandler.isResourceRequest(jakarta.faces.context.FacesContext)

getRendererTypeForResourceName

public String getRendererTypeForResourceName(String resourceName)

Description copied from class: ResourceHandler

Return the renderer-type for a Renderer that is capable of rendering this resource. The default implementation must return values according to the following table. If no renderer-type can be determined, null must be returned.

resource name to renderer-type mapping

example resource name	renderer-type
mycomponent.js	jakarta.faces.resource.Script
mystyle.css	jakarta.faces.resource.Stylesheet

Specified by:

getRendererTypeForResourceName in class ResourceHandler

Parameters:

resourceName - the resource name.

Returns:

the renderer type.

handleResourceRequest

public void handleResourceRequest(FacesContext context)
                           throws IOException

Description copied from class: ResourceHandler

This method specifies the contract for satisfying resource requests. This method is called from FacesServlet.service(jakarta.servlet.ServletRequest, jakarta.servlet.ServletResponse) after that method determines the current request is a resource request by calling ResourceHandler.isResourceRequest(jakarta.faces.context.FacesContext). Thus, handleResourceRequest may assume that the current request is a resource request.

The default implementation must implement an algorithm semantically identical to the following algorithm.

For discussion, in all cases when a status code is to be set, this spec talks only using the Jakarta Servlet API, but it is understood that in a portlet environment the appropriate equivalent API must be used.

• If the resourceIdentifier ends with any of the extensions listed in the value of the ResourceHandler.RESOURCE_EXCLUDES_PARAM_NAME init parameter, HttpServletRequest.SC_NOT_FOUND must be passed to HttpServletResponse.setStatus(), then handleResourceRequest must immediately return.

• Extract the resourceName from the resourceIdentifier by taking the substring of resourceIdentifier that starts at ResourceHandler.RESOURCE_IDENTIFIER.length() + 1 and goes to the end of resourceIdentifier. If no resourceName can be extracted, HttpServletRequest.SC_NOT_FOUND must be passed to HttpServletResponse.setStatus(), then handleResourceRequest must immediately return.

• Extract the libraryName from the request by looking in the request parameter map for an entry under the key "ln", without the quotes. If found, use its value as the libraryName.

• If resourceName and libraryName are present, call ResourceHandler.createResource(String, String) to create the Resource. If only resourceName is present, call ResourceHandler.createResource(String) to create the Resource. If the Resource cannot be successfully created, HttpServletRequest.SC_NOT_FOUND must be passed to HttpServletResponse.setStatus(), then handleResourceRequest must immediately return.

• Call Resource.userAgentNeedsUpdate(jakarta.faces.context.FacesContext). If this method returns false, HttpServletRequest.SC_NOT_MODIFIED must be passed to HttpServletResponse.setStatus(), then handleResourceRequest must immediately return.

• Pass the result of Resource.getContentType() to HttpServletResponse.setContentType.

• Call Resource.getResponseHeaders(). For each entry in this Map, call HttpServletResponse.setHeader(), passing the key as the first argument and the value as the second argument.

• Call Resource.getInputStream() and serve up the bytes of the resource to the response.

• Call HttpServletResponse.setContentLength() passing the byte count of the resource.

• If an IOException is thrown during any of the previous steps, log a descriptive, localized message, including the resourceName and libraryName (if present). Then, HttpServletRequest.SC_NOT_FOUND must be passed to HttpServletResponse.setStatus(), then handleResourceRequest must immediately return.

• In all cases in this method, any streams, channels, sockets, or any other IO resources must be closed before this method returns.

Specified by:

handleResourceRequest in class ResourceHandler

Parameters:

context - the FacesContext for this request

Throws:

IOException - when an I/O error occurs.

See Also:

• ResourceHandler.handleResourceRequest(jakarta.faces.context.FacesContext)