jakarta.faces.application.Resource Maven / Gradle / Ivy
Show all versions of jakarta.faces-api Show documentation
/*
* Copyright (c) 1997, 2020 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 jakarta.faces.application;
import java.io.IOException;
import java.io.InputStream;
import java.net.URL;
import java.util.Map;
import jakarta.faces.context.FacesContext;
import jakarta.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 = "jakarta.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);
}