javax.faces.application

## Class ResourceHandler

- java.lang.Object
- - javax.faces.application.ResourceHandler

- Direct Known Subclasses:
    ResourceHandlerWrapper

      public abstract class ResourceHandler
      extends 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` 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

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static 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).
    `static 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.
    `static String` | `RESOURCE_EXCLUDES_DEFAULT_VALUE` The default value for the `RESOURCE_EXCLUDES_PARAM_NAME` init param.
    `static 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.
    `static String` | `RESOURCE_IDENTIFIER` `Resource.getRequestPath()` returns the value of this constant as the prefix of the URI.
    `static 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.
    `static 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.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ResourceHandler()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Resource` | `createResource(String resourceName)` Create an instance of `ViewResource` given the argument `resourceName`.
    `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`.
    `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`.
    `Resource` | `createResourceFromId(String resourceId)` Create an instance of `Resource` given the argument `resourceId`.
    `ViewResource` | `createViewResource(FacesContext context, String resourceName)` Create an instance of `Resource` given the argument `resourceName`, which may contain "/" characters.
    `abstract String` | `getRendererTypeForResourceName(String resourceName)` Return the `renderer-type` for a `Renderer` 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)` Return `true` if the current request is a resource request.
    `boolean` | `isResourceURL(String url)` Return `true` if the argument `url` contains the string given by the value of the constant `RESOURCE_IDENTIFIER`, false otherwise.
    `abstract boolean` | `libraryExists(String libraryName)` Return `true` if the resource library named by the argument `libraryName` can be found.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### 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`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.