001    // Copyright 2006, 2008 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.tapestry5.ioc;
016    
017    import java.io.IOException;
018    import java.io.InputStream;
019    import java.net.URL;
020    import java.util.Locale;
021    
022    /**
023     * Represents a resource on the server that may be used for server side processing, or may be exposed to the client
024     * side. Generally, this represents an abstraction on top of files on the class path and files stored in the web
025     * application context.
026     * <p/>
027     * Resources are often used as map keys; they should be immutable and should implement hashCode() and equals().
028     */
029    public interface Resource
030    {
031    
032        /**
033         * Returns true if the resource exists; if a stream to the content of the file may be openned.
034         *
035         * @return true if the resource exists, false if it does not
036         */
037        boolean exists();
038    
039        /**
040         * Opens a stream to the content of the resource, or returns null if the resource does not exist.
041         *
042         * @return an open, buffered stream to the content, if available
043         */
044        InputStream openStream() throws IOException;
045    
046        /**
047         * Returns the URL for the resource, or null if it does not exist.
048         */
049        URL toURL();
050    
051        /**
052         * Returns a localized version of the resource. May return null if no such resource exists.
053         */
054        Resource forLocale(Locale locale);
055    
056        /**
057         * Returns a Resource based on a relative path, relative to the folder containing the resource. Understands the "."
058         * (current folder) and ".." (parent folder) conventions, and treats multiple sequential slashes as a single slash.
059         */
060        Resource forFile(String relativePath);
061    
062        /**
063         * Returns a new Resource with the extension changed (or, if the resource does not have an extension, the extension
064         * is added). The new Resource may not exist (that is, {@link #toURL()} may return null.
065         *
066         * @param extension to apply to the resource, such as "html" or "properties"
067         * @return the new resource
068         */
069        Resource withExtension(String extension);
070    
071        /**
072         * Returns the portion of the path up to the last forward slash; this is the directory or folder portion of the
073         * Resource.
074         */
075        String getFolder();
076    
077        /**
078         * Returns the file portion of the Resource path, everything that follows the final forward slash.
079         */
080        String getFile();
081    
082        /**
083         * Return the path (the combination of folder and file).
084         */
085        String getPath();
086    }