KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > jicengine > io > Resource


1 package org.jicengine.io;
2
3 import java.io.*;
4
5 /**
6  * <p>
7  * Provides a common interface for reading resources and resolving relative
8  * path-references.
9  * </p>
10  * <p>
11  * A resource is typically a file that contains data to be used by an
12  * application. Java provides various ways for reading resources: java.io.File,
13  * java.net.URL, java.lang.Class.getResourceAsStream(),
14  * java.lang.ClassLoader.getResourceAsStream(), etc.
15  * </p>
16  *
17  * <p>
18  * This class encapsulates all these under a common interface.
19  * </p>
20  *
21  * <p>
22  * Copyright (C) 2004 Timo Laitinen
23  * </p>
24  *
25  * @author .timo
26  * @version 1.0
27  */
28
29 public interface Resource {
30
31     /**
32      * A primary way reading the resource.
33      *
34      * @return InputStream
35      * @throws IOException if the reading fails - if the resource doesn't exist,
36      * for example.
37      */
38     public InputStream getInputStream() throws IOException;
39
40     /**
41      * Alternative way for reading text-based resources.
42      *
43      * @return A Reader that returns data from this Resource.
44      * @throws IOException if the reading fails - if the resource doesn't exist,
45      * for example.
46      */
47     public Reader getReader() throws IOException;
48
49     /**
50      * Writes the content of this resource into an OutputStream. This is an
51      * alternative way for obtaining the data of this Resource.
52      *
53      * @throws IOException if the content of this Resource isn't available - if
54      * the resource doesn't exist, for example.
55      */
56     public void writeTo(OutputStream out) throws IOException;
57
58     /**
59      * <p>
60      * Writes the content of this resource into a Writer. This is an
61      * alternative way for obtaining the data of this Resource.
62      * </p>
63      *
64      * @throws IOException if the content of this Resource isn't available - if
65      * the resource doesn't exist, for example.
66      */
67     public void writeTo(Writer writer) throws IOException;
68
69
70     /**
71      * <p>
72      * Tests whether the resource is available i.e. can be read.
73      * </p>
74      * <p>
75      * If this method returns true, the attempt to read this Resource (with getInputStream()
76      * or other methods) is not likely to fail. Unless the resource is somehow
77      * removed between the two method calls.
78      * </p>
79      * <p>
80      * If a false is return, the resource is not available.
81      * </p>
82      * <p>
83      * NOTE: testing whether a resource is available can be as
84      * resource-intensive as actually reading the resource.
85      * </p>
86      */
87     public boolean isAvailable();
88
89     /**
90    * <p>
91      * Returns the identifier of this resource.
92    * </p>
93      *
94    * <p>
95      * Depending on the kind of resource, the
96      * identifier could be a file-path, url, etc.
97    * </p>
98      * <p>
99      * The identifier is descriptive - it will help a human to find out what kind
100      * of resource is in question. It CAN NOT be used for creating new Resources or
101    * for reading resources. the format of the identifier varies and may be changed
102      * in the future.
103    * </p>
104      *
105      */
106     public String JavaDoc getIdentifier();
107
108     /**
109      * <p>
110      * Returns the http mime-type of this Resource, if this Resource has one.
111      * </p>
112      * <p>
113      * Mime-type information is an easy way to find out something about the
114      * type of content in a Resource. it also makes it easier to write Resource
115      * data into http-responses.
116      * </p>
117      *
118      * @return NOTE: this property is optional! null is returned if the mime-type
119      * information is not available. and most in cases it probably isn't.
120      */
121     public String JavaDoc getMimeType();
122
123     /**
124      * <p>
125      * Locates another Resource whose path is defined relative to this Resource.
126      * </p>
127      * <p>
128      * the path scheme used with files and urls is used for specifying relative
129      * paths.
130      * </p>
131      * <p>
132      * the method generally returns instances of the same Resource-subclass than
133      * the current instance, but this is not obligatory.
134      * </p>
135      * <p>
136      * NOTE:
137      * </p>
138      * <p>
139      * NOTE: there is no support for absolute paths. yet.
140      * </p>
141      * </p>
142      *
143      * @param relativePath name of the neighbouring resource. only relative paths
144      * are allowed, don't put the root mark '/' in the beginning. notations
145      * like '../' can be used (in most of the cases, at least) Windows-like
146      * paths '\joku\jotain.txt' won't work.
147      * @return a new Resource. The returned Resource is most likely of
148      * the same type as this resource (although there's no guarantee). In
149      * other words, if this Resource is a FileResource, the returned Resource
150      * will also be a FileResource.
151      * NOTE: this method doesn't necessary check the availability of the relative
152      * resource, because that may be too slow. if you want to make sure that the
153      * returned resource is available, you must examine the availability of the
154      * returned resource by your self.
155      *
156      * @throws IOException if a reference to the neighbouring resource couldn't be
157      * created.
158      *
159      */
160     public Resource getResource(String JavaDoc relativePath) throws IOException;
161
162 }
163
Popular Tags