001/* 002 * Copyright 2002-2017 the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * https://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016 017package org.springframework.core.io; 018 019import java.io.File; 020import java.io.IOException; 021import java.net.URI; 022import java.net.URL; 023 024/** 025 * Interface for a resource descriptor that abstracts from the actual 026 * type of underlying resource, such as a file or class path resource. 027 * 028 * <p>An InputStream can be opened for every resource if it exists in 029 * physical form, but a URL or File handle can just be returned for 030 * certain resources. The actual behavior is implementation-specific. 031 * 032 * @author Juergen Hoeller 033 * @since 28.12.2003 034 * @see #getInputStream() 035 * @see #getURL() 036 * @see #getURI() 037 * @see #getFile() 038 * @see WritableResource 039 * @see ContextResource 040 * @see UrlResource 041 * @see ClassPathResource 042 * @see FileSystemResource 043 * @see PathResource 044 * @see ByteArrayResource 045 * @see InputStreamResource 046 */ 047public interface Resource extends InputStreamSource { 048 049 /** 050 * Determine whether this resource actually exists in physical form. 051 * <p>This method performs a definitive existence check, whereas the 052 * existence of a {@code Resource} handle only guarantees a valid 053 * descriptor handle. 054 */ 055 boolean exists(); 056 057 /** 058 * Indicate whether the contents of this resource can be read via 059 * {@link #getInputStream()}. 060 * <p>Will be {@code true} for typical resource descriptors; 061 * note that actual content reading may still fail when attempted. 062 * However, a value of {@code false} is a definitive indication 063 * that the resource content cannot be read. 064 * @see #getInputStream() 065 */ 066 boolean isReadable(); 067 068 /** 069 * Indicate whether this resource represents a handle with an open stream. 070 * If {@code true}, the InputStream cannot be read multiple times, 071 * and must be read and closed to avoid resource leaks. 072 * <p>Will be {@code false} for typical resource descriptors. 073 */ 074 boolean isOpen(); 075 076 /** 077 * Return a URL handle for this resource. 078 * @throws IOException if the resource cannot be resolved as URL, 079 * i.e. if the resource is not available as descriptor 080 */ 081 URL getURL() throws IOException; 082 083 /** 084 * Return a URI handle for this resource. 085 * @throws IOException if the resource cannot be resolved as URI, 086 * i.e. if the resource is not available as descriptor 087 * @since 2.5 088 */ 089 URI getURI() throws IOException; 090 091 /** 092 * Return a File handle for this resource. 093 * @throws java.io.FileNotFoundException if the resource cannot be resolved as 094 * absolute file path, i.e. if the resource is not available in a file system 095 * @throws IOException in case of general resolution/reading failures 096 * @see #getInputStream() 097 */ 098 File getFile() throws IOException; 099 100 /** 101 * Determine the content length for this resource. 102 * @throws IOException if the resource cannot be resolved 103 * (in the file system or as some other known physical resource type) 104 */ 105 long contentLength() throws IOException; 106 107 /** 108 * Determine the last-modified timestamp for this resource. 109 * @throws IOException if the resource cannot be resolved 110 * (in the file system or as some other known physical resource type) 111 */ 112 long lastModified() throws IOException; 113 114 /** 115 * Create a resource relative to this resource. 116 * @param relativePath the relative path (relative to this resource) 117 * @return the resource handle for the relative resource 118 * @throws IOException if the relative resource cannot be determined 119 */ 120 Resource createRelative(String relativePath) throws IOException; 121 122 /** 123 * Determine a filename for this resource, i.e. typically the last 124 * part of the path: for example, "myfile.txt". 125 * <p>Returns {@code null} if this type of resource does not 126 * have a filename. 127 */ 128 String getFilename(); 129 130 /** 131 * Return a description for this resource, 132 * to be used for error output when working with the resource. 133 * <p>Implementations are also encouraged to return this value 134 * from their {@code toString} method. 135 * @see Object#toString() 136 */ 137 String getDescription(); 138 139}