javax.faces.application.ResourceHandler
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Object
public abstract class ResourceHandler
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.
| Field Summary | |
|---|---|
static String |
LOCALE_PREFIX
The name of a key within the
application message bundle named by the return from |
static String |
RESOURCE_CONTRACT_XML
The name of the marker file that
the implementation must scan for, within sub-directories
|
static String |
RESOURCE_EXCLUDES_DEFAULT_VALUE
The default value for the |
static String |
RESOURCE_EXCLUDES_PARAM_NAME
The |
static String |
RESOURCE_IDENTIFIER
|
static String |
WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME
If a
|
static String |
WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME
If a
|
| Constructor Summary | |
|---|---|
ResourceHandler()
|
|
| Method Summary | |
|---|---|
abstract Resource |
createResource(String resourceName)
Create an instance of
|
abstract Resource |
createResource(String resourceName,
String libraryOrContractName)
Create an instance of
|
abstract Resource |
createResource(String resourceName,
String libraryName,
String contentType)
Create an instance of
|
Resource |
createResourceFromId(String resourceId)
Create an instance of
|
ViewResource |
createViewResource(FacesContext context,
String resourceName)
Create an instance of |
abstract String |
getRendererTypeForResourceName(String resourceName)
Return the |
abstract void |
handleResourceRequest(FacesContext context)
This method specifies the contract for satisfying resource requests. |
abstract boolean |
isResourceRequest(FacesContext context)
Return |
boolean |
isResourceURL(String url)
Return |
abstract boolean |
libraryExists(String libraryName)
Return |
| Methods inherited from class java.lang.Object |
|---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
| Field Detail |
|---|
public static final 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 String 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.
public static final 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 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 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 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 String RESOURCE_EXCLUDES_DEFAULT_VALUE
The default value for the RESOURCE_EXCLUDES_PARAM_NAME init param.
| Constructor Detail |
|---|
public ResourceHandler()
| Method Detail |
|---|
public abstract Resource createResource(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.
NullPointerException - if resourceName is
null.
public ViewResource createViewResource(FacesContext context,
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 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 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.
NullPointerException - if resourceName is
null.public Resource createResourceFromId(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.
NullPointerException - if resourceId is
null.
public abstract Resource createResource(String resourceName,
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.
NullPointerExceptionresourceName is null
public abstract 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.
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.
NullPointerExceptionresourceName is null.public abstract boolean libraryExists(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.
public abstract void handleResourceRequest(FacesContext context)
throws 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 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 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
request
IOExceptionpublic 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
request
true if the current request is a resource
request, false otherwise.public boolean isResourceURL(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.
NullPointerException - if the argument url is null.public abstract String getRendererTypeForResourceName(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 |
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||