001: /*
002: * Copyright 2002-2007 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: * http://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:
017: package org.springframework.core.io;
018:
019: import java.io.File;
020: import java.io.IOException;
021: import java.net.URI;
022: import 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 FileSystemResource
039: * @see ClassPathResource
040: * @see UrlResource
041: * @see ByteArrayResource
042: * @see InputStreamResource
043: * @see org.springframework.web.context.support.ServletContextResource
044: */
045: public interface Resource extends InputStreamSource {
046:
047: /**
048: * Return whether this resource actually exists in physical form.
049: */
050: boolean exists();
051:
052: /**
053: * Return whether this resource represents a handle with an open
054: * stream. If true, the InputStream cannot be read multiple times,
055: * and must be read and closed to avoid resource leaks.
056: * <p>Will be false for all usual resource descriptors.
057: */
058: boolean isOpen();
059:
060: /**
061: * Return a URL handle for this resource.
062: * @throws IOException if the resource cannot be resolved as URL,
063: * i.e. if the resource is not available as descriptor
064: */
065: URL getURL() throws IOException;
066:
067: /**
068: * Return a URI handle for this resource.
069: * @throws IOException if the resource cannot be resolved as URI,
070: * i.e. if the resource is not available as descriptor
071: */
072: URI getURI() throws IOException;
073:
074: /**
075: * Return a File handle for this resource.
076: * @throws IOException if the resource cannot be resolved as absolute
077: * file path, i.e. if the resource is not available in a file system
078: */
079: File getFile() throws IOException;
080:
081: /**
082: * Create a resource relative to this resource.
083: * @param relativePath the relative path (relative to this resource)
084: * @return the resource handle for the relative resource
085: * @throws IOException if the relative resource cannot be determined
086: */
087: Resource createRelative(String relativePath) throws IOException;
088:
089: /**
090: * Return a filename for this resource, i.e. typically the last
091: * part of the path: for example, "myfile.txt".
092: */
093: String getFilename();
094:
095: /**
096: * Return a description for this resource,
097: * to be used for error output when working with the resource.
098: * <p>Implementations are also encouraged to return this value
099: * from their <code>toString</code> method.
100: * @see java.lang.Object#toString()
101: */
102: String getDescription();
103:
104: }
|