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}