javax.faces.application.Resource 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 java.io.InputStream;
import java.net.URL;
import java.util.Map;
import javax.faces.context.FacesContext;
/**
* 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 {
/**
* 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 caled
* contextRoot.
Discover if the FacesServlet is prefix or
* extension mapped, and the value of the mapping (including the
* leading '.' in the case of extension mapping). For discussion,
* this will be facesServletMapping.
*
* 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
*
* If {@link #getLibraryName} returns non-null,
* build up a string, called resourceMetaData for
* discussion, as follows:
*
*
*
* resourceMetaData = "?ln=" + {@link
* #getLibraryName}
*
*
*
* 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.
*/
public abstract URL getURL();
/**
* Call through to {@link
* #getRequestPath} and return the result.
*
* @return Call through to {@link #getRequestPath} and return the
* result.
*/
public String toString() {
return getRequestPath();
}
/**
* Return true if the
* user-agent requesting this resource needs an update. Returns
* false otherwise.
*
* @return true or false depending on
* whether or not the user-agent needs an update of this resource.
*/
public abstract boolean userAgentNeedsUpdate(FacesContext context);
}