Class ResourceHandler
- Direct Known Subclasses:
ResourceHandlerWrapper
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
and
resourceVersion
segments for the JAR packaging case.
Note that resourceName is the only required segment.
Encoding Resources
During the handling of view requests, the JSF 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 call Resource.getRequestPath()
to obtain the encoded URI for the resource. See Resource.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 JSF 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 calls Resource.getInputStream()
to obtain bytes of the resource. See
handleResourceRequest(javax.faces.context.FacesContext)
for the complete specification.
This usage of resources does not apply for resources that correspond to VDL resources.
- Since:
- 2.0
-
Field Summary
Modifier and TypeFieldDescriptionstatic final String
The name of a key within the application message bundle named by the return fromApplication.getMessageBundle()
whose value is the locale prefix used to find a packaged resource to return fromcreateResource(java.lang.String)
(or one of its variants).static final String
The name of the marker file that the implementation must scan for, within sub-directoriesMETA-INF/contracts
, to identify the set of available resource library contracts.static final String
The default value for theRESOURCE_EXCLUDES_PARAM_NAME
init param.static final String
TheServletContext
init parameter consulted by thehandleResourceRequest(javax.faces.context.FacesContext)
to tell which kinds of resources must never be served up in response to a resource request.static final String
Resource.getRequestPath()
returns the value of this constant as the prefix of the URI.static final String
If a<context-param>
with the param name equal to the value ofWEBAPP_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.static final String
If a<context-param>
with the param name equal to the value ofWEBAPP_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. -
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionabstract Resource
createResource
(String resourceName) Create an instance ofViewResource
given the argumentresourceName
.abstract Resource
createResource
(String resourceName, String libraryOrContractName) Create an instance ofResource
with a resourceName given by the value of the argumentresourceName
that is a member of the library named by the argumentlibraryName
.abstract Resource
createResource
(String resourceName, String libraryName, String contentType) Create an instance ofResource
with a resourceName given by the value of the argumentresourceName
that is a member of the library named by the argumentlibraryName
that claims to have the content-type given by the argumentcontent-type
.createResourceFromId
(String resourceId) Create an instance ofResource
given the argumentresourceId
.createViewResource
(FacesContext context, String resourceName) Create an instance ofResource
given the argumentresourceName
, which may contain "/" characters.abstract String
getRendererTypeForResourceName
(String resourceName) Return therenderer-type
for aRenderer
that is capable of rendering this resource.abstract void
handleResourceRequest
(FacesContext context) This method specifies the contract for satisfying resource requests.abstract boolean
isResourceRequest
(FacesContext context) Returntrue
if the current request is a resource request.boolean
isResourceURL
(String url) Returntrue
if the argumenturl
contains the string given by the value of the constantRESOURCE_IDENTIFIER
, false otherwise.abstract boolean
libraryExists
(String libraryName) Returntrue
if the resource library named by the argumentlibraryName
can be found.
-
Field Details
-
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.- See Also:
-
RESOURCE_CONTRACT_XML
The name of the marker file that the implementation must scan for, within sub-directories
META-INF/contracts
, to identify the set of available resource library contracts.- Since:
- 2.2
- See Also:
-
WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME
If a
<context-param>
with the param name equal to the value ofWEBAPP_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
- See Also:
-
WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME
If a
<context-param>
with the param name equal to the value ofWEBAPP_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
- See Also:
-
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 fromcreateResource(java.lang.String)
(or one of its variants).- See Also:
-
RESOURCE_EXCLUDES_PARAM_NAME
The
ServletContext
init parameter consulted by thehandleResourceRequest(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 theRESOURCE_EXCLUDES_DEFAULT_VALUE
constant is used. If manually specified, the given value entirely overrides the default one and does not supplement it.- See Also:
-
RESOURCE_EXCLUDES_DEFAULT_VALUE
The default value for the
RESOURCE_EXCLUDES_PARAM_NAME
init param.- See Also:
-
-
Constructor Details
-
ResourceHandler
public ResourceHandler()
-
-
Method Details
-
createResource
Create an instance of
ViewResource
given the argumentresourceName
. The content-type of the resource is derived by passing the resourceName toExternalContext.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 argumentresourceName
is of the formlibraryName/resourceName
, even whenresourceName
contains '/' characters.- Parameters:
resourceName
- the name of the resource.- Returns:
- a newly created
Resource
instance, suitable for use in encoding or decoding the named resource. - Throws:
NullPointerException
- ifresourceName
isnull
.
-
createViewResource
Create an instance of
Resource
given the argumentresourceName
, which may contain "/" characters. TheViewDeclarationLanguage
calls this method when it needs to load a view from a persistent store, such as a filesystem. This method is functionality equivalent tocreateResource(java.lang.String)
, but all callsites that need to load VDL views must use this method so that classes that want to decorate theResourceHandler
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. AFacesContext
must be present before calling this method. To preserve compatibility with prior revisions of the specification, a default implementation must be provided that callscreateResource(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 JSF 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 argumentresoureName
exists as a resource in the resource library contract, return it. Otherwise, return the resource (not in the resource library contract), if found. Otherwise, returnnull
.- Parameters:
context
- theFacesContext
for this request.resourceName
- the name of the resource to be interpreted as a view by theViewDeclarationLanguage
.- Returns:
- a newly created
ViewResource
instance, suitable for use by theViewDeclarationLanguage
. - Throws:
NullPointerException
- ifresourceName
isnull
.- Since:
- 2.2
-
createResourceFromId
Create an instance of
Resource
given the argumentresourceId
. The content-type of the resource is derived by passing the resourceName toExternalContext.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.
- Parameters:
resourceId
- the resource identifier of the resource.- Returns:
- a newly created
Resource
instance, suitable for use in encoding or decoding the named resource. - Throws:
NullPointerException
- ifresourceId
isnull
.- Since:
- 2.2
-
createResource
Create an instance of
Resource
with a resourceName given by the value of the argumentresourceName
that is a member of the library named by the argumentlibraryName
. The content-type of the resource is derived by passing the resourceName toExternalContext.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.- Parameters:
resourceName
- the name of the resource.libraryOrContractName
- the name of the library (or contract) in which this resource resides, may benull
. 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.
-
createResource
public abstract Resource createResource(String resourceName, String libraryName, String contentType) Create an instance of
Resource
with a resourceName given by the value of the argumentresourceName
that is a member of the library named by the argumentlibraryName
that claims to have the content-type given by the argumentcontent-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.- Parameters:
resourceName
- the name of the resource.libraryName
- the name of the library in which this resource resides, may benull
. May not include relative paths, such as "../".contentType
- the mime content that thisResource
instance will return fromResource.getContentType()
. If the value isnull
, The content-type of the resource is derived by passing the resourceName toExternalContext.getMimeType(java.lang.String)
- Returns:
- a newly created
Resource
instance, suitable for use in encoding or decoding the named resource.
-
libraryExists
Return
true
if the resource library named by the argumentlibraryName
can be found. If there is alocalePrefix
for this application, as defined inLOCALE_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.- Since:
- 2.0
-
handleResourceRequest
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 callingisResourceRequest(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 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 toHttpServletResponse.setStatus()
, thenhandleResourceRequest
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 toHttpServletResponse.setStatus()
, thenhandleResourceRequest
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 theResource
. If only resourceName is present, callcreateResource(String)
to create theResource
. If theResource
cannot be successfully created,HttpServletRequest.SC_NOT_FOUND
must be passed toHttpServletResponse.setStatus()
, thenhandleResourceRequest
must immediately return.Call
Resource.userAgentNeedsUpdate(javax.faces.context.FacesContext)
. If this method returns false,HttpServletRequest.SC_NOT_MODIFIED
must be passed toHttpServletResponse.setStatus()
, thenhandleResourceRequest
must immediately return.Pass the result of
Resource.getContentType()
toHttpServletResponse.setContentType.
Call
Resource.getResponseHeaders()
. For each entry in thisMap
, callHttpServletResponse.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 toHttpServletResponse.setStatus()
, thenhandleResourceRequest
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.
- Parameters:
context
- theFacesContext
for this request- Throws:
IOException
-
isResourceRequest
Return
true
if the current request is a resource request. This method is called byFacesServlet.service(javax.servlet.ServletRequest, javax.servlet.ServletResponse)
to determine if this request is a view request or a resource request.- Parameters:
context
- theFacesContext
for this request- Returns:
true
if the current request is a resource request,false
otherwise.
-
isResourceURL
Return
true
if the argumenturl
contains the string given by the value of the constantRESOURCE_IDENTIFIER
, false otherwise.- Parameters:
url
- the url to inspect for the presence ofRESOURCE_IDENTIFIER
.- Throws:
NullPointerException
- if the argument url isnull
.
-
getRendererTypeForResourceName
Return the
renderer-type
for aRenderer
that is capable of rendering this resource. The default implementation must return values according to the following table. If norenderer-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
-