public abstract Class ResourceHandler

Library name of Jakarta Faces script resource.

Since

2.3

Resource name of Jakarta Faces script resource.

Since

2.3

Library name of Jakarta Faces script resource.

Resource name of Jakarta Faces script resource.

The name of a key within the application message bundle named by the return from Application#getMessageBundle whose value is the locale prefix used to find a packaged resource to return from createResource (or one of its variants).

This file must be located in META-INF/contracts/<contractName>/ in a jar file that contains a resource library contract, where <contractName> is the name of the contract. If the jar file contains multiple contracts, the marker file must be present in each one. See “constant field values” for the name of the file that must be placed at that location.

Since

2.2

The default value for the RESOURCE_EXCLUDES_PARAM_NAME init param.

The ServletContext init parameter consulted by the handleResourceRequest to tell which kinds of resources must never be served up in response to a resource request. The value of this parameter is a single space separated list of file extensions, including the leading '.' character (without the quotes). If not specified, the default value given in the value of the RESOURCE_EXCLUDES_DEFAULT_VALUE constant is used. If manually specified, the given value entirely overrides the default one and does not supplement it.

Resource#getRequestPath returns the value of this constant as the prefix of the URI. handleResourceRequest(jakarta.faces.context.FacesContext) looks for the value of this constant within the request URI to determine if the request is a resource request or a view request.

If a <context-param> with the param name equal to the value of WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME exists, the runtime must interpret its value as a path, relative to the web app root, where resource library contracts are to be located. This param value must not start with a "/", though it may contain "/" characters. If no such <context-param> exists, or its value is invalid, the value "contracts", without the quotes, must be used by the runtime as the value.

Since

2.2

If a <context-param> with the param name equal to the value of WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME exists, the runtime must interpret its value as a path, relative to the web app root, where resources are to be located. This param value must not start with a "/", though it may contain "/" characters. If no such <context-param> exists, or its value is invalid, the value "resources", without the quotes, must be used by the runtime as the value.

Since

2.2

Create an instance of ViewResource given the argument resourceName. The content-type of the resource is derived by passing the resourceName to jakarta.faces.context.ExternalContext#getMimeType

Parameters

resourceName:String

the name of the resource.

Returns:Resource

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

Exceptions

NullPointerException:

if resourceName is null.

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 jakarta.faces.context.ExternalContext#getMimeType.

Parameters

resourceName:String

the name of the resource.

libraryOrContractName:String

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

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

Exceptions

NullPointerException:

if resourceName is null

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.

Parameters

resourceName:String

the name of the resource.

libraryName:String

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

contentType:String

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 jakarta.faces.context.ExternalContext#getMimeType

Returns:Resource

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

Exceptions

NullPointerException:

if resourceName is null.

Create an instance of Resource given the argument resourceId. The content-type of the resource is derived by passing the resourceName to jakarta.faces.context.ExternalContext#getMimeType

Parameters

resourceId:String

the resource identifier of the resource.

Returns:Resource

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

Exceptions

NullPointerException:

if resourceId is null.

Since

2.2

Create an instance of Resource given the argument resourceName, which may contain "/" characters. The jakarta.faces.view.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 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 jakarta.faces.context.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 createResource(java.lang.String).

Parameters

context:FacesContext

the FacesContext for this request.

resourceName:String

the name of the resource to be interpreted as a view by the jakarta.faces.view.ViewDeclarationLanguage.

Returns:ViewResource

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

Exceptions

NullPointerException:

if resourceName is null.

Since

2.2

Return the renderer-type for a jakarta.faces.render.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.

Parameters

resourceName:String

the resource name.

Returns:String

the renderer type.

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

Parameters

facesContext:FacesContext

The FacesContext for this request.

path:String

The initial path from which to start looking for view resources

maxDepth:int

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

options:ResourceVisitOption[]

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

Returns:Stream<String>

the Stream of view resource names

Since

2.3

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 as the resourceName parameter.

This method works as if invoking it were equivalent to evaluating the expression:

getViewResources(facesContext, start, Integer.MAX_VALUE, options)

Parameters

facesContext:FacesContext

The FacesContext for this request.

path:String

The initial path from which to start looking for view resources

options:ResourceVisitOption[]

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

Returns:Stream<String>

the Stream of view resource names

Since

2.3

This method specifies the contract for satisfying resource requests. This method is called from jakarta.faces.webapp.FacesServlet#service after that method determines the current request is a resource request by calling isResourceRequest. Thus, handleResourceRequest may assume that the current request is a resource request.

Parameters

context:FacesContext

the jakarta.faces.context.FacesContext for this request

Exceptions

IOException:

when an I/O error occurs.

Returns whether the resource as identified by given resource and library name has been rendered. The default implementation must during the render response phase of the current view return true when the resource has been marked as rendered via markResourceRendered(FacesContext, String, String).

Parameters

context:FacesContext

The FacesContext for this request.

resourceName:String

The name of the resource.

libraryName:String

The name of the library in which this resource resides, may be null.

Returns:boolean

Whether the resource as identified by given resource and library name has been rendered.

Annotations

@SuppressWarnings:unchecked

Since

2.3

Return true if the current request is a resource request. This method is called by jakarta.faces.webapp.FacesServlet#service to determine if this request is a view request or a resource request.

Parameters

context:FacesContext

the jakarta.faces.context.FacesContext for this request

Returns:boolean

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

Return true if the argument url contains the string given by the value of the constant ResourceHandler#RESOURCE_IDENTIFIER, false otherwise.

Parameters

url:String

the url to inspect for the presence of ResourceHandler#RESOURCE_IDENTIFIER.

Returns:boolean

true if this is a resource URL, false otherwise.

Exceptions

NullPointerException:

if the argument url is null.

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

Parameters

libraryName:String

the library name.

Returns:boolean

true if the library exists, false otherwise.

Since

2.0

Mark the resource as identified by given resource and library name as rendered. The default implementation must ensure that isResourceRendered(FacesContext, String, String) will return true when the resource has already been rendered during the render response phase of the current view.

Parameters

context:FacesContext

The FacesContext for this request.

resourceName:String

The name of the resource.

libraryName:String

The name of the library in which the resource resides, may be null.

Annotations

@SuppressWarnings:unchecked

Since

2.3