001    // Copyright 2006, 2008, 2012 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 opened. A resource exists
034         * if {@link #toURL()} returns a non-null value. Starting in release 5.3.4, the result of this is cached.
035         *
036         * @return true if the resource exists, false if it does not
037         */
038        boolean exists();
039    
040        /**
041         * Opens a stream to the content of the resource, or returns null if the resource does not exist.
042         *
043         * @return an open, buffered stream to the content, if available
044         */
045        InputStream openStream() throws IOException;
046    
047        /**
048         * Returns the URL for the resource, or null if it does not exist. This value is lazily computed; starting in 5.3.4, subclasses may cache
049         * the result.
050         */
051        URL toURL();
052    
053        /**
054         * Returns a localized version of the resource. May return null if no such resource exists. Starting in release
055         * 5.3.4, the result of this method is cached internally.
056         */
057        Resource forLocale(Locale locale);
058    
059        /**
060         * Returns a Resource based on a relative path, relative to the folder containing the resource. Understands the "."
061         * (current folder) and ".." (parent folder) conventions, and treats multiple sequential slashes as a single slash.
062         */
063        Resource forFile(String relativePath);
064    
065        /**
066         * Returns a new Resource with the extension changed (or, if the resource does not have an extension, the extension
067         * is added). The new Resource may not exist (that is, {@link #toURL()} may return null.
068         *
069         * @param extension
070         *         to apply to the resource, such as "html" or "properties"
071         * @return the new resource
072         */
073        Resource withExtension(String extension);
074    
075        /**
076         * Returns the portion of the path up to the last forward slash; this is the directory or folder portion of the
077         * Resource.
078         */
079        String getFolder();
080    
081        /**
082         * Returns the file portion of the Resource path, everything that follows the final forward slash.
083         */
084        String getFile();
085    
086        /**
087         * Return the path (the combination of folder and file).
088         */
089        String getPath();
090    }