    001// Copyright 2006, 2007, 2008, 2009 The Apache Software Foundation
    002//
    003// Licensed under the Apache License, Version 2.0 (the "License");
    004// you may not use this file except in compliance with the License.
    005// You may obtain a copy of the License at
    006//
    007//     http://www.apache.org/licenses/LICENSE-2.0
    008//
    009// Unless required by applicable law or agreed to in writing, software
    010// distributed under the License is distributed on an "AS IS" BASIS,
    011// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    012// See the License for the specific language governing permissions and
    013// limitations under the License.
    014
    015package org.apache.tapestry5.http.services;
    016
    017import java.io.File;
    018import java.net.URL;
    019import java.util.List;
    020
    021/**
    022 * An API agnostic version of {@link javax.servlet.ServletContext}, used to bridge the gaps between the Servlet API and
    023 * the Portlet API.
    024 */
    025public interface Context
    026{
    027    /**
    028     * Returns a URL to a resource stored within the context. The path should start with a leading slash.
    029     *
    030     * @param path to the resource (with a leading slash)
    031     * @return the URL for the path, or null if the path does not correspond to a file.
    032     */
    033    URL getResource(String path);
    034
    035    /**
    036     * Attempts to find the actual file, on the file system, that would be provided by the servlet container for the
    037     * given path (which must start with a leading slash). This may return null if no such file exists, or if the
    038     * resource in question is packaged inside a WAR.  If packaged inside a WAR, the contents may be accessed via {@link
    039     * #getResource(String)}.
    040     *
    041     * @param path to  the resource (with a leading slash)
    042     * @return the underlying File, or null if no such file
    043     */
    044    File getRealFile(String path);
    045
    046    /**
    047     * Returns an initial parameter value defined by servlet.
    048     */
    049    String getInitParameter(String name);
    050
    051    /**
    052     * Looks for resources within the web application within the supplied path. The list will be recurively expanded, as
    053     * necessary. The path must start with a leading slash, and usually ends with a slash as well.
    054     *
    055     * @param path to search for (should start with a leading slash)
    056     * @return the matches, sorted alphabetically
    057     */
    058    List<String> getResourcePaths(String path);
    059
    060    /**
    061     * Returns an attribute previously stored into the context with the given name.
    062     *
    063     * @param name used to retrieve the attribute
    064     * @return the attribute, or null if not found
    065     */
    066    Object getAttribute(String name);
    067
    068    /**
    069     * Returns the names of all attributes of the context, sorted alphabetically.
    070     */
    071    List<String> getAttributeNames();
    072
    073    /**
    074     * Returns the MIME content type of the specified file, or null if no content type is known. MIME types are built-in
    075     * to servlet containers and may be futher specified via the web application deployment descriptor.
    076     *
    077     * @param file name of file
    078     * @return the presumed MIME content type, or null if not known
    079     * @since 5.1.0.0
    080     */
    081    String getMimeType(String file);
    082}