    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    }