1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 package org.apache.struts.flow.core.source;
18
19 import java.io.IOException;
20 import java.io.InputStream;
21
22 /***
23 * This interface provides a simple interface for accessing a source of data.
24 * <p>
25 * When the <code>Source</code> object is no longer needed
26 * it must be released using the {@link SourceResolver}. This is very similar to
27 * looking up components from a <code>ServiceSelector</code>.
28 * In fact a source object can implement most lifecycle interfaces
29 * like Composable, Initializable, Disposable etc.
30 * <p>
31 * The data content can be constant or change over time.
32 * Using the {@link #getInputStream()} method you get always the up-to-date content.
33 * <p>
34 * If you want to track changes of the source object, this interface
35 * offers you some support for it by providing a SourceValidity object.
36 * <p>
37 * How does the caching work?
38 * The first time you get a Source object, you simply ask
39 * it for it's content via getInputStream() and then get the validity
40 * object by invoking getValidity. (Further calls to getValidity always
41 * return the same object! This is not updated!)
42 * The caching algorithm can now store this validity object together
43 * with the system identifier of the source.
44 * The next time, the caching algorithm wants to check if the cached
45 * content is still valid. It has a validity object already to check
46 * against.
47 * <p>
48 * If it is still the same Source than the first time, you
49 * have to call refresh() in order to discard the stored validity
50 * in the Source object. If it is a new Source object,
51 * calling refresh() should do no harm.
52 * After that an up-to-date validity object can retrieved by calling
53 * getValidity(). This can be used to test if the content is still valid
54 * as discribed in the source validity documentation.
55 * If the content is still valid, the cache knows what to do, if not,
56 * the new content can be get using getInputStream().
57 * So either after a call to getValidity() or the getInputStream the
58 * validity object must be the same until refresh is called!
59 *
60 * @author <a href="mailto:dev@avalon.apache.org">Avalon Development Team</a>
61 * @version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:26 $
62 */
63 public interface Source
64 {
65 /***
66 * Does this source exist ?
67 *
68 * @return true if the source exists
69 */
70 boolean exists();
71
72 /***
73 * Return an <code>InputStream</code> to read from the source.
74 * This is the data at the point of invocation of this method,
75 * so if this is Modifiable, you might get different content
76 * from two different invocations.
77 *
78 * The returned stream must be closed by the calling code.
79 *
80 * @return the <code>InputStream</code> to read data from (never <code>null</code>).
81 * @throws IOException if some I/O problem occurs.
82 * @throws SourceNotFoundException if the source doesn't exist.
83 */
84 InputStream getInputStream()
85 throws IOException, SourceNotFoundException;
86
87 /***
88 * Get the absolute URI for this source.
89 *
90 * @return the source URI.
91 */
92 String getURI();
93
94 /***
95 * Return the URI scheme identifier, i.e. the part preceding the fist ':' in the URI
96 * (see <a href="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>).
97 * <p>
98 * This scheme can be used to get the {@link SourceFactory} responsible for this object.
99 *
100 * @return the URI scheme.
101 */
102 String getScheme();
103
104 /***
105 * Get the Validity object. This can either wrap the last modification date or
106 * some expiry information or anything else describing this object's validity.
107 * <p>
108 * If it is currently not possible to calculate such an information,
109 * <code>null</code> is returned.
110 *
111 * @return the validity, or <code>null</code>.
112 */
113 SourceValidity getValidity();
114
115 /***
116 * Refresh the content of this object after the underlying data content has changed.
117 * <p>
118 * Some implementations may cache some values to speedup sucessive calls. Refreshing
119 * ensures you get the latest information.
120 */
121 void refresh();
122
123 /***
124 * Get the mime-type of the content described by this object.
125 * If the source is not able to determine the mime-type by itself
126 * this can be <code>null</code>.
127 *
128 * @return the source's mime-type or <code>null</code>.
129 */
130 String getMimeType();
131
132 /***
133 * Get the content length of this source's content or -1 if the length is
134 * unknown.
135 *
136 * @return the source's content length or -1.
137 */
138 long getContentLength();
139
140 /***
141 * Get the last modification date of this source. The date is
142 * measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970),
143 * and is <code>0</code> if it's unknown.
144 *
145 * @return the last modification date or <code>0</code>.
146 */
147 long getLastModified();
148
149 }