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}