001// Copyright 2005 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.tapestry.web;
016
017import java.io.InputStream;
018import java.net.URL;
019import java.util.Set;
020
021import org.apache.tapestry.describe.Describable;
022
023/**
024 * A representation of a set of servlets (or portlets) packaged together as a web application
025 * archive. Attributes stored within the context are global to all 'lets (but not distributed across
026 * a server cluster).
027 * 
028 * @author Howard M. Lewis Ship
029 */
030public interface WebContext extends AttributeHolder, InitializationParameterHolder, Describable
031{
032    /**
033     * Returns a URL to the resource that is mapped to a specified path. The path must begin with a
034     * "/" and is interpreted as relative to the current context root.
035     */
036
037    public URL getResource(String path);
038
039    /**
040     * Returns the MIME type of the specified file, or null if the MIME type is not known.
041     */
042    public String getMimeType(String resourcePath);
043    
044    /**
045     * Returns a directory-like listing of all the paths to resources within 
046     * the web application whose longest sub-path matches the supplied 
047     * path argument. Paths indicating subdirectory paths end with a slash (/). 
048     * The returned paths are all relative to the root of the web application 
049     * and have a leading '/'. 
050     * @param path  partial path used to match the resources, which must start with a '/'
051     * @return a Set containing the directory listing, or null if there are no resources 
052     * in the web application whose path begins with the supplied path.
053     */
054    public Set getResourcePaths(String path);
055    
056    /**
057     * Returns the resource located at the named path as an <code>InputStream</code>
058     * object.
059     * @param path a <code>String</code> specifying the path to the resource
060     * @return the <code>InputStream</code> returned to the servlet, 
061     *  or <code>null</code> if no resource exists at the specified path
062     */
063    public InputStream getResourceAsStream(String path);
064    
065    /**
066     * Returns a <code>String</code> containing the real path for a given virtual path. 
067     * For example, the path "/index.html" returns the absolute file path 
068     * on the server's filesystem would be served by a request for 
069     * "http://host/contextPath/index.html", where contextPath is the 
070     * context path of this WebContext.
071     * 
072     * @param path a <code>String</code> specifying a virtual path
073     * @return a <code>String</code> specifying the real path, or <code>null</code> if the 
074     *  translation cannot be performed
075     */
076    public String getRealPath(String path);
077}