javax.faces.application.Resource Maven / Gradle / Ivy
/*
* 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.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 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 (null == resourceName) {
throw new NullPointerException("PENDING_I18N: 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 EL expressions present in the
* resource must be evaluated before serving the bytes of the
* resource. Note that due to browser and server caching, EL
* expressions in a resource file will generally only be evaluated
* once, when the resource is first served up. Therefore, using EL
* 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);
}