"Fossies" - the Fresh Open Source Software Archive

Member "apidocs/src-html/org/apache/tapestry5/ioc/Resource.html" (9 Sep 2020, 11019 Bytes) of package /linux/www/apache-tapestry-5.6.1-apidocs.zip:


Caution: In this restricted "Fossies" environment the current HTML page may not be correctly presentated and may have some non-functional links. You can here alternatively try to browse the pure source code or just view or download the uninterpreted raw source code. If the rendering is insufficient you may try to find and view the page on the project site itself.

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.ioc;
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}