|
DRAFT | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
java.lang.Objectjavax.faces.application.ResourceHandler
public abstract class ResourceHandler
ResourceHandler is the
run-time API by which UIComponent and
Renderer instances 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.
For the default implementation, resources packaged in the classpath must reside under the JAR entry name
META-INF/resources/<resourceIdentifier>
<resourceIdentifier> consists of several
segments, specified as follows.
[localePrefix/][libraryName/][libraryVersion/]resourceName[/resourceVersion]
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.
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.
| Field Summary | |
|---|---|
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_EXCLUDES_DEFAULT_VALUE
The default value for the |
static java.lang.String |
RESOURCE_EXCLUDES_PARAM_NAME
The |
static java.lang.String |
RESOURCE_IDENTIFIER
|
| Constructor Summary | |
|---|---|
ResourceHandler()
|
|
| Method Summary | |
|---|---|
abstract Resource |
createResource(java.lang.String resourceName)
Create an instance of
|
abstract Resource |
createResource(java.lang.String resourceName,
java.lang.String libraryName)
Create an instance of
|
abstract Resource |
createResource(java.lang.String resourceName,
java.lang.String libraryName,
java.lang.String contentType)
Create an instance of
|
abstract java.lang.String |
getRendererTypeForResourceName(java.lang.String resourceName)
Return the |
abstract void |
handleResourceRequest(FacesContext context)
This method specifies the contract for satisfying resource requests. |
abstract boolean |
isResourceRequest(FacesContext context)
Return |
abstract boolean |
libraryExists(java.lang.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 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 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.
| Constructor Detail |
|---|
public ResourceHandler()
| Method Detail |
|---|
public abstract Resource createResource(java.lang.String resourceName)
Create an instance of
Resource 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
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 abstract Resource createResource(java.lang.String resourceName,
java.lang.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. 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
resourceName - the name of the resource.libraryName - the name of the library in which this resource
resides, may be null.
Resource instance, suitable
for use in encoding or decoding the named resource.
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
resourceName - the name of the resource.libraryName - the name of the library in which this resource
resides, may be null.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.
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.
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 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. 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
java.io.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 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 |
|
DRAFT | ||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright © 2009 Sun Microsystems, Inc. All Rights Reserved. Use is subject to license terms.
Generated on 24-November-2009 03:24