public abstract class ResourceHandler
extends java.lang.Object
ResourceHandler is the run-time API by which
UIComponent
and Renderer
instances, and the
ViewDeclarationLanguage
can reference Resource
instances.
An implementation of this class must be thread-safe.
Packaging Resources
ResourceHandler defines a path based packaging convention for resources. The default implementation of
ResourceHandler
must support packaging resources in the classpath or in the web application root. See section JSF.2.6.1 of the spec prose document linked in the overview summary for the normative specification of packaging resources.Briefly, The default implementation must support packaging resources in the web application root under the path
resources/<resourceIdentifier>
relative to the web app root. "resources" is the default location, but this location can be changed by the value of the
WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME
<context-param>
.For the default implementation, resources packaged in the classpath must reside under the JAR entry name
META-INF/resources/<resourceIdentifier>
In the case of Faces Flows packaged within jar files, resources packaged in the classpath must reside under the jar entry name
META-INF/flows/<resourceIdentifier>
<resourceIdentifier>
consists of several segments, specified as follows.
[localePrefix/][libraryName/][libraryVersion/]resourceName[/resourceVersion]
None of the segments in the resourceIdentifier may be relative paths, such as ‘../otherLibraryName’. The implementation is not required to support the
libraryVersion
andresourceVersion
segments for the JAR packaging case.Note that resourceName is the only required segment.
Encoding Resources
During the handling of view requests, the Jakarta Server Face run-time may be called upon to encode a resource in such a way as to instruct the user-agent to make a subsequent resource request. This behavior is orchestrated by one of the resource renderers (
ScriptRenderer
,StylesheetRenderer
,ImageRenderer
), which all callResource.getRequestPath()
to obtain the encoded URI for the resource. SeeResource.getRequestPath()
and the Standard HTML RenderKit specification for the complete specification.This usage of resources does not apply for resources that correspond to VDL resources.
Decoding Resources
During the handling of resource requests, the Jakarta Server Faces run-time will be called upon to decode a resource in such a way as to serve up the bytes of the resource to the user-agent. This behavior is orchestrated by
handleResourceRequest(javax.faces.context.FacesContext)
, which callsResource.getInputStream()
to obtain bytes of the resource. SeehandleResourceRequest(javax.faces.context.FacesContext)
for the complete specification.This usage of resources does not apply for resources that correspond to VDL resources.
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
JSF_SCRIPT_LIBRARY_NAME
Library name of Jakarta Server Faces script resource. |
static java.lang.String |
JSF_SCRIPT_RESOURCE_NAME
Resource name of Jakarta Server Faces script resource. |
static java.lang.String |
LOCALE_PREFIX
The name of a key within the application message bundle named by the return from
|
static java.lang.String |
RESOURCE_CONTRACT_XML
This file must be located in |
static java.lang.String |
RESOURCE_EXCLUDES_DEFAULT_VALUE
The default value for the |
static java.lang.String |
RESOURCE_EXCLUDES_PARAM_NAME
The |
static java.lang.String |
RESOURCE_IDENTIFIER
|
static java.lang.String |
WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME
If a |
static java.lang.String |
WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME
If a |
Constructor and Description |
---|
ResourceHandler() |
Modifier and Type | Method and Description |
---|---|
abstract Resource |
createResource(java.lang.String resourceName)
Create an instance of |
abstract Resource |
createResource(java.lang.String resourceName,
java.lang.String libraryOrContractName)
Create an instance of |
abstract Resource |
createResource(java.lang.String resourceName,
java.lang.String libraryName,
java.lang.String contentType)
Create an instance of |
Resource |
createResourceFromId(java.lang.String resourceId)
Create an instance of |
ViewResource |
createViewResource(FacesContext context,
java.lang.String resourceName)
Create an instance of |
abstract java.lang.String |
getRendererTypeForResourceName(java.lang.String resourceName)
Return the |
java.util.stream.Stream<java.lang.String> |
getViewResources(FacesContext facesContext,
java.lang.String path,
int maxDepth,
ResourceVisitOption... options)
Return a |
java.util.stream.Stream<java.lang.String> |
getViewResources(FacesContext facesContext,
java.lang.String path,
ResourceVisitOption... options)
Return a |
abstract void |
handleResourceRequest(FacesContext context)
This method specifies the contract for satisfying resource requests. |
boolean |
isResourceRendered(FacesContext context,
java.lang.String resourceName,
java.lang.String libraryName)
Returns whether the resource as identified by given resource and library name has been rendered. |
abstract boolean |
isResourceRequest(FacesContext context)
Return |
boolean |
isResourceURL(java.lang.String url)
Return |
abstract boolean |
libraryExists(java.lang.String libraryName)
Return |
void |
markResourceRendered(FacesContext context,
java.lang.String resourceName,
java.lang.String libraryName)
Mark the resource as identified by given resource and library name as rendered. |
public static final java.lang.String RESOURCE_IDENTIFIER
Resource.getRequestPath()
returns the value of this constant as the prefix of the URI.
handleResourceRequest(javax.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.
public static final java.lang.String JSF_SCRIPT_RESOURCE_NAME
Resource name of Jakarta Server Faces script resource.
public static final java.lang.String JSF_SCRIPT_LIBRARY_NAME
Library name of Jakarta Server Faces script resource.
public static final java.lang.String RESOURCE_CONTRACT_XML
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.
public static final java.lang.String WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME
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.
public static final java.lang.String WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME
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.
public static final java.lang.String LOCALE_PREFIX
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(java.lang.String)
(or one of its variants).
public static final java.lang.String RESOURCE_EXCLUDES_PARAM_NAME
The ServletContext
init parameter consulted by the
handleResourceRequest(javax.faces.context.FacesContext)
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.
public static final java.lang.String RESOURCE_EXCLUDES_DEFAULT_VALUE
The default value for the RESOURCE_EXCLUDES_PARAM_NAME
init param.
public abstract Resource createResource(java.lang.String resourceName)
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 JSF.2.6.1.4 of the spec prose document
linked in the overview summary
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.
resourceName
- the name of the resource.Resource
instance, suitable for use in encoding or
decoding the named resource.java.lang.NullPointerException
- if resourceName
is null
.public ViewResource createViewResource(FacesContext context, java.lang.String resourceName)
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 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 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 spec prose document section Resource Library Contracts in the Request Processing Lifecycle chapter).
Considering the web app root.
Considering faces flows (at the locations specified in the spec prose document section Faces Flows in the Using Jakarta Server Faces in Web Applications chapter).
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
.
context
- the FacesContext
for this request.resourceName
- the name of the resource to be interpreted as a view by the
ViewDeclarationLanguage
.ViewResource
instance, suitable for use by the
ViewDeclarationLanguage
.java.lang.NullPointerException
- if resourceName
is null
.public java.util.stream.Stream<java.lang.String> getViewResources(FacesContext facesContext, java.lang.String path, int maxDepth, ResourceVisitOption... options)
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
createViewResource(javax.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.
facesContext
- The FacesContext
for this request.path
- The initial path from which to start looking for view resourcesmaxDepth
- 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.Stream
of view resource namespublic java.util.stream.Stream<java.lang.String> getViewResources(FacesContext facesContext, java.lang.String path, ResourceVisitOption... options)
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
createViewResource(javax.faces.context.FacesContext, java.lang.String)
as the resourceName
parameter.
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 view resourcesoptions
- The options to influence the traversal. See ResourceVisitOption
for
details on those.Stream
of view resource namespublic Resource createResourceFromId(java.lang.String resourceId)
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 JSF.2.6.1.3 of the spec prose document linked in the overview summary. New requirements were introduced in version 2.2 of the specification.
resourceId
- the resource identifier of the resource.Resource
instance, suitable for use in encoding or
decoding the named resource.java.lang.NullPointerException
- if resourceId
is null
.public abstract Resource createResource(java.lang.String resourceName, java.lang.String libraryOrContractName)
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 JSF.2.6.1.4 of the spec prose document
linked in the overview summary
must be executed to create the Resource
. New
requirements were introduced in version 2.2 of the specification.
resourceName
- the name of the resource.libraryOrContractName
- 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
"../".Resource
instance, suitable for use in encoding or
decoding the named resource.java.lang.NullPointerException
- if resourceName
is null
public abstract Resource createResource(java.lang.String resourceName, java.lang.String libraryName, java.lang.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
.
The algorithm specified in section JSF.2.6.1.4 of the spec prose document
linked in the overview summary
must be executed to create the Resource
. New
requirements were introduced in version 2.2 of the specification.
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)
Resource
instance, suitable for use in encoding or
decoding the named resource.java.lang.NullPointerException
- if resourceName
is null
.public abstract boolean libraryExists(java.lang.String libraryName)
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, this scenario is enabled.
libraryName
- the library name.true
if the library exists, false
otherwise.public abstract void handleResourceRequest(FacesContext context) throws java.io.IOException
This method specifies the contract for satisfying resource requests. This method is called
from FacesServlet.service(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
after that method determines the current
request is a resource request by calling isResourceRequest(javax.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
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
and goes to the end of resourceIdentifier.
If no resourceName can be extracted, RESOURCE_IDENTIFIER
.length() + 1HttpServletRequest.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
createResource(String, String)
to create the Resource
. If only
resourceName is present, call 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(javax.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.
context
- the FacesContext
for this requestjava.io.IOException
- when an I/O error occurs.public abstract boolean isResourceRequest(FacesContext context)
Return true
if the current request is a resource request. This method is called
by FacesServlet.service(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
to determine if this request is a view
request or a resource request.
context
- the FacesContext
for this requesttrue
if the current request is a resource request, false
otherwise.public boolean isResourceURL(java.lang.String url)
Return true
if the argument url
contains the string given by the value of the
constant RESOURCE_IDENTIFIER
, false otherwise.
url
- the url to inspect for the presence of
RESOURCE_IDENTIFIER
.true
if this is a resource URL, false
otherwise.java.lang.NullPointerException
- if the argument url is null
.public abstract java.lang.String getRendererTypeForResourceName(java.lang.String resourceName)
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.
example resource name | renderer-type |
---|---|
mycomponent.js | javax.faces.resource.Script |
mystyle.css | javax.faces.resource.Stylesheet |
resourceName
- the resource name.public void markResourceRendered(FacesContext context, java.lang.String resourceName, java.lang.String libraryName)
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.
context
- The FacesContext
for this request.resourceName
- The name of the resource.libraryName
- The name of the library in which the resource resides, may be
null
.public boolean isResourceRendered(FacesContext context, java.lang.String resourceName, java.lang.String libraryName)
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)
.
context
- The FacesContext
for this request.resourceName
- The name of the resource.libraryName
- The name of the library in which this resource resides, may be
null
.