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 015package org.apache.tapestry5.ioc; 016 017import java.io.IOException; 018import java.io.InputStream; 019import java.net.URL; 020import 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 */ 029public 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 * <p/> 036 * Starting in 5.4, some "virtual resources", may return true even though {@link #toURL()} returns null. 037 * 038 * @return true if the resource exists, false if it does not 039 */ 040 boolean exists(); 041 042 /** 043 * Opens a stream to the content of the resource, or returns null if the resource does not exist. The native 044 * input stream supplied by the resource is wrapped in a {@link java.io.BufferedInputStream}. 045 * 046 * @return an open, buffered stream to the content, if available 047 */ 048 InputStream openStream() throws IOException; 049 050 /** 051 * 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 052 * the result. Starting in 5.4, some "virtual resources" may return null. 053 */ 054 URL toURL(); 055 056 /** 057 * Returns a localized version of the resource. May return null if no such resource exists. Starting in release 058 * 5.3.4, the result of this method is cached internally. 059 */ 060 Resource forLocale(Locale locale); 061 062 /** 063 * Returns a Resource based on a relative path, relative to the folder containing the resource. Understands the "." 064 * (current folder) and ".." (parent folder) conventions, and treats multiple sequential slashes as a single slash. 065 * <p/> 066 * Virtual resources (resources fabricated at runtime) return themselves. 067 */ 068 Resource forFile(String relativePath); 069 070 /** 071 * Returns a new Resource with the extension changed (or, if the resource does not have an extension, the extension 072 * is added). The new Resource may not exist (that is, {@link #toURL()} may return null. 073 * 074 * @param extension 075 * to apply to the resource, such as "html" or "properties" 076 * @return the new resource 077 */ 078 Resource withExtension(String extension); 079 080 /** 081 * Returns the portion of the path up to the last forward slash; this is the directory or folder portion of the 082 * Resource. 083 */ 084 String getFolder(); 085 086 /** 087 * Returns the file portion of the Resource path, everything that follows the final forward slash. 088 * <p/> 089 * Starting in 5.4, certain kinds of "virtual resources" may return null here. 090 */ 091 String getFile(); 092 093 /** 094 * Return the path (the combination of folder and file). 095 * <p/> 096 * Starting in 5.4, certain "virtual resources", may return an arbitrary value here. 097 */ 098 String getPath(); 099}