Class ResourceHandler

Field Detail

• RESOURCE_IDENTIFIER

  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.

  See Also:

  Constant Field Values

• RESOURCE_CONTRACT_XML

  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.

  Since:

  2.2

  See Also:

  Constant Field Values

• WEBAPP_RESOURCES_DIRECTORY_PARAM_NAME

  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.

  Since:

  2.2

  See Also:

  Constant Field Values

• WEBAPP_CONTRACTS_DIRECTORY_PARAM_NAME

  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.

  Since:

  2.2

  See Also:

  Constant Field Values

• LOCALE_PREFIX

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

  See Also:

  Constant Field Values

• RESOURCE_EXCLUDES_PARAM_NAME

  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.

  See Also:

  Constant Field Values

• RESOURCE_EXCLUDES_DEFAULT_VALUE

  public static final String RESOURCE_EXCLUDES_DEFAULT_VALUE

  The default value for the RESOURCE_EXCLUDES_PARAM_NAME init param.

  See Also:

  Constant Field Values

Constructor Detail

• ResourceHandler

  public ResourceHandler()

Method Detail

• createResource

  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.

  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 - if resourceName is null.

• createViewResource

  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.

  Parameters:

  context - the FacesContext for this request.

  resourceName - the name of the resource to be interpreted as a view by the ViewDeclarationLanguage.

  Returns:

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

  Throws:

  NullPointerException - if resourceName is null.

  Since:

  2.2

• createResourceFromId

  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.

  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 - if resourceId is null.

  Since:

  2.2

• createResource

  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.

  Parameters:

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

  Returns:

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

  Throws:

  NullPointerException - if resourceName is null

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

  Parameters:

  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)

  Returns:

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

  Throws:

  NullPointerException - if resourceName is null.

• libraryExists

  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.

  Since:

  2.0

• handleResourceRequest

  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() + 1 and goes to the end of resourceIdentifier. If no resourceName can be extracted, HttpServletRequest.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.

  Parameters:

  context - the FacesContext for this request

  Throws:

  IOException

• isResourceRequest

  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.

  Parameters:

  context - the FacesContext for this request

  Returns:

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

• isResourceURL

  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.

  Parameters:

  url - the url to inspect for the presence of RESOURCE_IDENTIFIER.

  Throws:

  NullPointerException - if the argument url is null.

• getRendererTypeForResourceName

  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

  Retour à la première page de API Java Table des matières Haut