Start line:  
End line:  

Snippet Preview

Snippet HTML Code

Stack Overflow Questions
  /*
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
   *
   * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
   *
   * The contents of this file are subject to the terms of either the GNU
   * General Public License Version 2 only ("GPL") or the Common Development
   * and Distribution License("CDDL") (collectively, the "License").  You
   * may not use this file except in compliance with the License.  You can
  * obtain a copy of the License at
  * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
  * or packager/legal/LICENSE.txt.  See the License for the specific
  * language governing permissions and limitations under the License.
  *
  * When distributing the software, include this License Header Notice in each
  * file and include the License file at packager/legal/LICENSE.txt.
  *
  * GPL Classpath Exception:
  * Oracle designates this particular file as subject to the "Classpath"
  * exception as provided by Oracle in the GPL Version 2 section of the License
  * file that accompanied this code.
  *
  * Modifications:
  * If applicable, add the following below the License Header, with the fields
  * enclosed by brackets [] replaced by your own identifying information:
  * "Portions Copyright [year] [name of copyright owner]"
  *
  * Contributor(s):
  * If you wish your version of this file to be governed by only the CDDL or
  * only the GPL Version 2, indicate your decision by adding "[Contributor]
  * elects to include this software in this distribution under the [CDDL or GPL
  * Version 2] license."  If you don't indicate a single choice of license, a
  * recipient has the option to distribute your version of this file under
  * either the CDDL, the GPL Version 2 or to extend the choice of license to
  * its licensees as provided above.  However, if you add GPL Version 2 code
  * and therefore, elected the GPL Version 2 license, then the option applies
  * only if the new code is made subject to such option by the copyright
  * holder.
  */
 
 package javax.faces.application;
 
 

ResourceHandler is the run-time API by which javax.faces.component.UIComponent and javax.faces.render.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]

    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.

Decoding Resources

Since:
2.0
public abstract class ResourceHandler {

    

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_IDENTIFIER = "/javax.faces.resource";


    

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 LOCALE_PREFIX = 
	"javax.faces.resource.localePrefix";



    

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_PARAM_NAME =
          "javax.faces.RESOURCE_EXCLUDES";

    

The default value for the RESOURCE_EXCLUDES_PARAM_NAME init param.

    public static final String RESOURCE_EXCLUDES_DEFAULT_VALUE =
          ".class .jsp .jspx .properties .xhtml .groovy";
    // ---------------------------------------------------------- Public Methods
    

    

Create an instance of Resource given the argument resourceName. The content-type of the resource is derived by passing the resourceName to javax.faces.context.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

Parameters:
resourceName the name of the resource.
Returns:
a newly created Resource instance, suitable for use in encoding or decoding the named resource.
Throws:
java.lang.NullPointerException if resourceName is null.
    public abstract Resource createResource(String resourceName);


    

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 javax.faces.context.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

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 "../".
Returns:
a newly created Resource instance, suitable for use in encoding or decoding the named resource.
Throws:
NullPointerException if resourceName is null
    public abstract Resource createResource(String resourceName,
                                            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 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

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 javax.faces.context.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.
    public abstract Resource createResource(String resourceName,
                                            String libraryName,
                                            String contentType);
    
    

Return true if the resource library named by the argument libraryName can be found.

Since:
2.0
    
    public abstract boolean libraryExists(String libraryName);


    

This method specifies the contract for satisfying resource requests. This method is called from javax.faces.webapp.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(java.lang.String,java.lang.String) to create the Resource. If only resourceName is present, call createResource(java.lang.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 javax.faces.context.FacesContext for this request
    public abstract void handleResourceRequest(FacesContext context)
    throws IOException;


    

Return true if the current request is a resource request. This method is called by javax.faces.webapp.FacesServlet.service(javax.servlet.ServletRequest,javax.servlet.ServletResponse) to determine if this request is a view request or a resource request.

Parameters:
context the javax.faces.context.FacesContext for this request
Returns:
true if the current request is a resource request, false otherwise.
    public abstract boolean isResourceRequest(FacesContext context);
    
    

Return the renderer-type for a javax.faces.render.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 namerenderer-type
mycomponent.jsjavax.faces.resource.Script
mystyle.cssjavax.faces.resource.Stylesheet
    
    public abstract String getRendererTypeForResourceName(String resourceName);
    
New to GrepCode? Check out our FAQ X