All Downloads are FREE. Search and download functionalities are using the official Maven repository.

javax.faces.application.ResourceHandler Maven / Gradle / Ivy

Go to download

This is the master POM file for Sun's Implementation of the JSF 2.1 Specification.

There is a newer version: 2.2.20
Show newest version
/*
 * 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;

import java.io.IOException;

import javax.faces.context.FacesContext;


/**
 * 

ResourceHandler is the * run-time API by which {@link javax.faces.component.UIComponent} and * {@link javax.faces.render.Renderer} instances can reference {@link * 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 {@link Resource#getRequestPath} * to obtain the encoded URI for the resource. See {@link * 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 {@link #handleResourceRequest}, which calls {@link * Resource#getInputStream} to obtain bytes of the resource. See * {@link #handleResourceRequest} for the complete specification.

    * *
* *
* * @since 2.0 */ public abstract class ResourceHandler { /** *

{@link Resource#getRequestPath} returns the * value of this constant as the prefix of the URI. {@link * #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 {@link * Application#getMessageBundle} whose value is the locale prefix * used to find a packaged resource to return from {@link * #createResource} (or one of its variants). */ public static final String LOCALE_PREFIX = "javax.faces.resource.localePrefix"; /** *

The ServletContext init * parameter consulted by the {@link #handleResourceRequest} 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 {@link * #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 {@link * #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 {@link * javax.faces.context.ExternalContext#getMimeType}

*
*

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

*
* @param resourceName the name of the resource. * * @throws NullPointerException if resourceName is * null. * * @return a newly created Resource instance, suitable * for use in encoding or decoding the named resource. */ 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 * {@link javax.faces.context.ExternalContext#getMimeType}.

* *
*

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

*
* @param resourceName the name of the resource. * * @param libraryName the name of the library in which this resource * resides, may be null. May not include relative * paths, such as "../". * * @throws NullPointerException if * resourceName is null * * @return a newly created Resource instance, suitable * for use in encoding or decoding the named resource. */ 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

*
* @param resourceName the name of the resource. * * @param libraryName the name of the library in which this resource * resides, may be null. May not include relative * paths, such as "../". * * @param contentType the mime content that this * Resource instance will return from {@link * Resource#getContentType}. If the value is null, The * content-type of the resource is derived by passing the * resourceName to {@link * javax.faces.context.ExternalContext#getMimeType}

* * @throws NullPointerException if * resourceName is null. * * @return a newly created Resource instance, suitable * for use in encoding or decoding the named resource. */ 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 * {@link javax.faces.webapp.FacesServlet#service} after that method * determines the current request is a resource request by calling * {@link #isResourceRequest}. 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 {@link * #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 {@link * #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 {@link #createResource(String, String)} to create * the Resource. If only resourceName is * present, call {@link #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 {@link 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 {@link Resource#getContentType} to * HttpServletResponse.setContentType.

  • * *
  • Call {@link 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 {@link 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.

  • * *
* *
* * @param context the {@link 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 * {@link javax.faces.webapp.FacesServlet#service} to determine if * this request is a view request or a resource * request.

* * @param context the {@link javax.faces.context.FacesContext} for this * request * @return true if the current request is a resource * request, false otherwise. */ public abstract boolean isResourceRequest(FacesContext context); /** *

Return the renderer-type for a * {@link 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); }




© 2015 - 2024 Weber Informatics LLC | Privacy Policy