001: package org.jicengine.io;
002:
003: import java.io.*;
004:
005: /**
006: * <p>
007: * Provides a common interface for reading resources and resolving relative
008: * path-references.
009: * </p>
010: * <p>
011: * A resource is typically a file that contains data to be used by an
012: * application. Java provides various ways for reading resources: java.io.File,
013: * java.net.URL, java.lang.Class.getResourceAsStream(),
014: * java.lang.ClassLoader.getResourceAsStream(), etc.
015: * </p>
016: *
017: * <p>
018: * This class encapsulates all these under a common interface.
019: * </p>
020: *
021: * <p>
022: * Copyright (C) 2004 Timo Laitinen
023: * </p>
024: *
025: * @author .timo
026: * @version 1.0
027: */
028:
029: public interface Resource {
030:
031: /**
032: * A primary way reading the resource.
033: *
034: * @return InputStream
035: * @throws IOException if the reading fails - if the resource doesn't exist,
036: * for example.
037: */
038: public InputStream getInputStream() throws IOException;
039:
040: /**
041: * Alternative way for reading text-based resources.
042: *
043: * @return A Reader that returns data from this Resource.
044: * @throws IOException if the reading fails - if the resource doesn't exist,
045: * for example.
046: */
047: public Reader getReader() throws IOException;
048:
049: /**
050: * Writes the content of this resource into an OutputStream. This is an
051: * alternative way for obtaining the data of this Resource.
052: *
053: * @throws IOException if the content of this Resource isn't available - if
054: * the resource doesn't exist, for example.
055: */
056: public void writeTo(OutputStream out) throws IOException;
057:
058: /**
059: * <p>
060: * Writes the content of this resource into a Writer. This is an
061: * alternative way for obtaining the data of this Resource.
062: * </p>
063: *
064: * @throws IOException if the content of this Resource isn't available - if
065: * the resource doesn't exist, for example.
066: */
067: public void writeTo(Writer writer) throws IOException;
068:
069: /**
070: * <p>
071: * Tests whether the resource is available i.e. can be read.
072: * </p>
073: * <p>
074: * If this method returns true, the attempt to read this Resource (with getInputStream()
075: * or other methods) is not likely to fail. Unless the resource is somehow
076: * removed between the two method calls.
077: * </p>
078: * <p>
079: * If a false is return, the resource is not available.
080: * </p>
081: * <p>
082: * NOTE: testing whether a resource is available can be as
083: * resource-intensive as actually reading the resource.
084: * </p>
085: */
086: public boolean isAvailable();
087:
088: /**
089: * <p>
090: * Returns the identifier of this resource.
091: * </p>
092: *
093: * <p>
094: * Depending on the kind of resource, the
095: * identifier could be a file-path, url, etc.
096: * </p>
097: * <p>
098: * The identifier is descriptive - it will help a human to find out what kind
099: * of resource is in question. It CAN NOT be used for creating new Resources or
100: * for reading resources. the format of the identifier varies and may be changed
101: * in the future.
102: * </p>
103: *
104: */
105: public String getIdentifier();
106:
107: /**
108: * <p>
109: * Returns the http mime-type of this Resource, if this Resource has one.
110: * </p>
111: * <p>
112: * Mime-type information is an easy way to find out something about the
113: * type of content in a Resource. it also makes it easier to write Resource
114: * data into http-responses.
115: * </p>
116: *
117: * @return NOTE: this property is optional! null is returned if the mime-type
118: * information is not available. and most in cases it probably isn't.
119: */
120: public String getMimeType();
121:
122: /**
123: * <p>
124: * Locates another Resource whose path is defined relative to this Resource.
125: * </p>
126: * <p>
127: * the path scheme used with files and urls is used for specifying relative
128: * paths.
129: * </p>
130: * <p>
131: * the method generally returns instances of the same Resource-subclass than
132: * the current instance, but this is not obligatory.
133: * </p>
134: * <p>
135: * NOTE:
136: * </p>
137: * <p>
138: * NOTE: there is no support for absolute paths. yet.
139: * </p>
140: * </p>
141: *
142: * @param relativePath name of the neighbouring resource. only relative paths
143: * are allowed, don't put the root mark '/' in the beginning. notations
144: * like '../' can be used (in most of the cases, at least) Windows-like
145: * paths '\joku\jotain.txt' won't work.
146: * @return a new Resource. The returned Resource is most likely of
147: * the same type as this resource (although there's no guarantee). In
148: * other words, if this Resource is a FileResource, the returned Resource
149: * will also be a FileResource.
150: * NOTE: this method doesn't necessary check the availability of the relative
151: * resource, because that may be too slow. if you want to make sure that the
152: * returned resource is available, you must examine the availability of the
153: * returned resource by your self.
154: *
155: * @throws IOException if a reference to the neighbouring resource couldn't be
156: * created.
157: *
158: */
159: public Resource getResource(String relativePath) throws IOException;
160:
161: }
|