    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005//     http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.commons;
    014
    015import java.io.IOException;
    016import java.io.InputStream;
    017import java.net.URL;
    018import java.util.Locale;
    019
    020/**
    021 * Represents a resource on the server that may be used for server side processing, or may be exposed to the client
    022 * side. Generally, this represents an abstraction on top of files on the class path and files stored in the web
    023 * application context.
    024 *
    025 * Resources are often used as map keys; they should be immutable and should implement hashCode() and equals().
    026 */
    027public interface Resource
    028{
    029
    030    /**
    031     * Returns true if the resource exists; if a stream to the content of the file may be opened. A resource exists
    032     * if {@link #toURL()} returns a non-null value. Starting in release 5.3.4, the result of this is cached.
    033     *
    034     * Starting in 5.4, some "virtual resources", may return true even though {@link #toURL()} returns null.
    035     *
    036     * @return true if the resource exists, false if it does not
    037     */
    038    boolean exists();
    039
    040
    041    /**
    042     * Returns true if the resource is virtual, meaning this is no underlying file. Many operations are unsupported
    043     * on virtual resources, including {@link #toURL()}, {@link #forLocale(java.util.Locale)},
    044     * {@link #withExtension(String)}, {@link #getFile()}, {@link #getFolder()}, {@link #getPath()}}; these
    045     * operations will throw an {@link java.lang.UnsupportedOperationException}.
    046     *
    047     * @since 5.4
    048     */
    049    boolean isVirtual();
    050
    051    /**
    052     * Opens a stream to the content of the resource, or returns null if the resource does not exist. The native
    053     * input stream supplied by the resource is wrapped in a {@link java.io.BufferedInputStream}.
    054     *
    055     * @return an open, buffered stream to the content, if available
    056     */
    057    InputStream openStream() throws IOException;
    058
    059    /**
    060     * 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
    061     * the result.  Starting in 5.4, some "virtual resources" may return null.
    062     */
    063    URL toURL();
    064
    065    /**
    066     * Returns a localized version of the resource. May return null if no such resource exists. Starting in release
    067     * 5.3.4, the result of this method is cached internally.
    068     */
    069    Resource forLocale(Locale locale);
    070
    071    /**
    072     * Returns a Resource based on a relative path, relative to the folder containing the resource. Understands the "."
    073     * (current folder) and ".." (parent folder) conventions, and treats multiple sequential slashes as a single slash.
    074     *
    075     * Virtual resources (resources fabricated at runtime) return themselves.
    076     */
    077    Resource forFile(String relativePath);
    078
    079    /**
    080     * Returns a new Resource with the extension changed (or, if the resource does not have an extension, the extension
    081     * is added). The new Resource may not exist (that is, {@link #toURL()} may return null.
    082     *
    083     * @param extension
    084     *         to apply to the resource, such as "html" or "properties"
    085     * @return the new resource
    086     */
    087    Resource withExtension(String extension);
    088
    089    /**
    090     * Returns the portion of the path up to the last forward slash; this is the directory or folder portion of the
    091     * Resource.
    092     */
    093    String getFolder();
    094
    095    /**
    096     * Returns the file portion of the Resource path, everything that follows the final forward slash.
    097     *
    098     * Starting in 5.4, certain kinds of "virtual resources" may return null here.
    099     */
    100    String getFile();
    101
    102    /**
    103     * Return the path (the combination of folder and file).
    104     *
    105     * Starting in 5.4, certain "virtual resources", may return an arbitrary value here.
    106     */
    107    String getPath();
    108}