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    
015    package org.apache.tapestry.web;
016    
017    import java.io.InputStream;
018    import java.net.URL;
019    import java.util.Set;
020    
021    import 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     */
030    public 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        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        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        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        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        String getRealPath(String path);
077    }