javax.faces.application.Resource Maven / Gradle / Ivy
Show all versions of jakarta.faces Show documentation
/*
* Copyright (c) 1997, 2018 Oracle and/or its affiliates. All rights reserved.
*
* This program and the accompanying materials are made available under the
* terms of the Eclipse Public License v. 2.0, which is available at
* http://www.eclipse.org/legal/epl-2.0.
*
* This Source Code may also be made available under the following Secondary
* Licenses when the conditions for such availability set forth in the
* Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
* version 2 with the GNU Classpath Exception, which is available at
* https://www.gnu.org/software/classpath/license.html.
*
* SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0
*/
package javax.faces.application;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.util.Map;
import javax.faces.context.FacesContext;
import javax.servlet.ServletRegistration;
/**
*
* An instance
* of Resource is a Java object representation of the artifact that is served up in
* response to a resource request from the client. Instances of Resource are
* normally created and initialized via calls to {@link ResourceHandler#createResource}. See the
* documentation for {@link ResourceHandler} for more information.
*
*
*
*
* @since 2.0
*/
public abstract class Resource extends ViewResource {
/**
*
* This constant is used as the key in the component attribute map of a composite component to
* associate the component with its Resource instance. The value for this key is
* the actual Resource instance.
*
*
*/
public static final String COMPONENT_RESOURCE_KEY = "javax.faces.application.Resource.ComponentResource";
private String contentType;
private String libraryName;
private String resourceName;
// ---------------------------------------------------------- Public Methods
/**
*
* Return the MIME content-type for this resource.
*
*
* @return the MIME content-type for this resource.
*/
public String getContentType() {
return contentType;
}
/**
*
*
* Set the MIME content-type for this resource. The default implementation performs no
* validation on the argument.
*
*
* @param contentType the MIME content-type for this resource. The default implementation must
* accept null as a parameter.
*/
public void setContentType(String contentType) {
this.contentType = contentType;
}
/**
*
* Return the libraryName for this resource. May be null. The libraryName for a
* resource is an optional String that indicates membership in a "resource library". All
* resources with the same libraryName belong to the same "resource library". The "resource
* library" concept allows disambiguating resources that have the same resourceName. See
* {@link ResourceHandler} for more information.
*
*
* @return Return the libraryName for this resource. May be null.
*/
public String getLibraryName() {
return libraryName;
}
/**
*
* Set the libraryName for this resource.
*
*
* @param libraryName the libraryName for this resource. The default implementation must accept
* null for the libraryName.
*/
public void setLibraryName(String libraryName) {
this.libraryName = libraryName;
}
/**
*
* Return the resourceName for this resource. Will never be null. All Resource
* instances must have a resourceName.
*
*
* @return Return the resourceName for this resource. Will never be null.
*/
public String getResourceName() {
return resourceName;
}
/**
*
* Set the resourceName for this resource.
*
*
* @param resourceName a non-null String.
*
* @throws NullPointerException if argument resourceName is null.
*/
public void setResourceName(String resourceName) {
if (resourceName == null) {
throw new NullPointerException("All resources must have a non-null resourceName.");
}
this.resourceName = resourceName;
}
/**
*
* If the current request is a resource request, (that
* is, {@link ResourceHandler#isResourceRequest} returns true), return an
* InputStream containing the bytes of the resource. Otherwise, throw an
* IOException.
*
*
* @return an InputStream containing the bytes of the resource.
*
*
* Any Jakarta Expression Language expressions present in the resource must be evaluated before serving the bytes
* of the resource. Note that due to browser and server caching, Jakarta Expression Language expressions in a
* resource file will generally only be evaluated once, when the resource is first
* served up. Therefore, using Jakarta Expression Language expressions that refer to per-request data is not
* advisable since this data can become stale.
*
*
* @throws IOException if the current request is not a resource request.
*/
public abstract InputStream getInputStream() throws IOException;
/**
*
* Returns a mutable Map<String, String> whose entries will be sent as
* response headers during {@link ResourceHandler#handleResourceRequest}. The entries in this
* map must not persist beyond the scope of a single request. Any modifications made to the map
* after the resource has been served will be ignored by the run-time.
*
*
* @return a mutable Map<String, String> of headers that will be included
* with the response.
*/
public abstract Map getResponseHeaders();
/**
*
* Return a path to this resource
* such that, when the browser resolves it against the base URI for the view that includes the
* resource, and issues a GET request to the resultant fully qualified URL, the bytes of the
* resource are returned in response.
*
*
*
*
*
* The default implementation must implement the following algorithm. For discussion, the return
* result from this method will be called result.
*
*
*
*
* -
*
* Get the context-root for this web application, not ending in slash. For discussion this will
* be called contextRoot.
*
*
*
* -
*
* Discover if the FacesServlet is prefix (path) mapped, extension mapped, or exact
* mapped (as defined by Servlet.12.2.) and the value of the mapping (including the leading '.'
* in the case of extension mapping). For discussion, this will be facesServletMapping.
*
*
*
*
* If exact mapped, result must be the following if and only if the FacesServlet is
* mapped to the exact URL pattern {@link ResourceHandler#RESOURCE_IDENTIFIER} +
* {@link #getResourceName}
*
*
*
*
* result = contextRoot + {@link
* ResourceHandler#RESOURCE_IDENTIFIER} + {@link #getResourceName}
*
*
*
*
* If exact mapped, and the FacesServlet is not mapped to the exact URL pattern
* {@link ResourceHandler#RESOURCE_IDENTIFIER} + {@link #getResourceName} do the following:
*
*
*
* Retrieve the existing mappings of the FacesServlet, e.g. using
* {@link ServletRegistration#getMappings()}, and from those pick any prefix mapping or
* extension mapping. If no such mapping is found, throw an {@link IllegalStateException}. If
* such mapping is found remove the * character from that mapping, take that as the
* new facesServletMapping and continue with evaluating this mapping as specified below
* for if prefix mapped and for if extension mapped
*
*
* If prefix mapped, result must be
*
*
*
*
* result = contextRoot + '/' +
* facesServletMapping + {@link
* ResourceHandler#RESOURCE_IDENTIFIER} + '/' + {@link
* #getResourceName}
*
*
*
*
* If extension mapped, result must be
*
*
*
*
* result = contextRoot + {@link
* ResourceHandler#RESOURCE_IDENTIFIER} + {@link #getResourceName} +
* facesServletMapping
*
*
*
*
*
* -
*
* Build up a string, called resourceMetaData which is an & separated string of
* name=value pairs suitable for inclusion in a URL query string.
*
*
*
*
*
* If {@link #getLibraryName} returns non-null, resourceMetaData must
* include "ln=" + the return from {@link #getLibraryName}
*
*
*
* If there is a localePrefix for this application, as defined in
* {@link ResourceHandler#LOCALE_PREFIX}, resourceMetaData must include "loc=" +
* the localePrefix.
*
*
*
*
* If this resource is contained in a resource library contract, resourceMetaData
* must include "con=" + the name of the resource library contract.
*
*
*
*
*
* Append "?" + resourceMetaData to result.
*
*
*
*
* -
*
* Make it portlet safe by passing the result through {@link ViewHandler#getResourceURL}.
*
*
*
*
*
*
*
* @return the path to this resource, intended to be included in the encoded view that is sent
* to the browser when sending a faces response.
*/
public abstract String getRequestPath();
/**
*
* Return an actual URL instance that refers to this resource instance.
*
*
* @return Return an actual URL instance that refers to this resource instance.
*/
@Override
public abstract URL getURL();
/**
*
* Call through to {@link #getRequestPath} and return the result.
*
*
* @return Call through to {@link #getRequestPath} and return the result.
*/
@Override
public String toString() {
return getRequestPath();
}
/**
*
* Return true if the user-agent
* requesting this resource needs an update. If the
* {@code If-Modified-Since} HTTP header is available for this request, its value must be
* consulted, as specified in Section 14.25 of IETF RFC 2616, to determine the result.
* Returns false if the user-agent does not need an update for this resource.
*
*
* @param context the Faces context.
* @return true or false depending on whether or not the user-agent
* needs an update of this resource.
*/
public abstract boolean userAgentNeedsUpdate(FacesContext context);
}