javax.faces.application.ResourceHandler Maven / Gradle / Ivy
Show all versions of jsf-api Show documentation
/*
* 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 name
*
* renderer-type
*
*
*
*
*
* mycomponent.js
*
* javax.faces.resource.Script
*
*
*
* mystyle.css
*
* javax.faces.resource.Stylesheet
*
*
*/
public abstract String getRendererTypeForResourceName(String resourceName);
}