KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > excalibur > source > Source


1 /*
2  * Copyright 2002-2004 The Apache Software Foundation
3  * Licensed under the Apache License, Version 2.0 (the "License");
4  * you may not use this file except in compliance with the License.
5  * You may obtain a copy of the License at
6  *
7  * http://www.apache.org/licenses/LICENSE-2.0
8  *
9  * Unless required by applicable law or agreed to in writing, software
10  * distributed under the License is distributed on an "AS IS" BASIS,
11  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
12  * implied.
13  *
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 package org.apache.excalibur.source;
18
19 import java.io.IOException JavaDoc;
20 import java.io.InputStream JavaDoc;
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      * @return the <code>InputStream</code> to read data from (never <code>null</code>).
79      * @throws IOException if some I/O problem occurs.
80      * @throws SourceNotFoundException if the source doesn't exist.
81      */
82     InputStream JavaDoc getInputStream()
83         throws IOException JavaDoc, SourceNotFoundException;
84
85     /**
86      * Get the absolute URI for this source.
87      *
88      * @return the source URI.
89      */
90     String JavaDoc getURI();
91
92     /**
93      * Return the URI scheme identifier, i.e. the part preceding the fist ':' in the URI
94      * (see <a HREF="http://www.ietf.org/rfc/rfc2396.txt">RFC 2396</a>).
95      * <p>
96      * This scheme can be used to get the {@link SourceFactory} responsible for this object.
97      *
98      * @return the URI scheme.
99      */
100     String JavaDoc getScheme();
101     
102     /**
103      * Get the Validity object. This can either wrap the last modification date or
104      * some expiry information or anything else describing this object's validity.
105      * <p>
106      * If it is currently not possible to calculate such an information,
107      * <code>null</code> is returned.
108      *
109      * @return the validity, or <code>null</code>.
110      */
111     SourceValidity getValidity();
112
113     /**
114      * Refresh the content of this object after the underlying data content has changed.
115      * <p>
116      * Some implementations may cache some values to speedup sucessive calls. Refreshing
117      * ensures you get the latest information.
118      */
119     void refresh();
120
121     /**
122      * Get the mime-type of the content described by this object.
123      * If the source is not able to determine the mime-type by itself
124      * this can be <code>null</code>.
125      *
126      * @return the source's mime-type or <code>null</code>.
127      */
128     String JavaDoc getMimeType();
129
130     /**
131      * Get the content length of this source's content or -1 if the length is
132      * unknown.
133      *
134      * @return the source's content length or -1.
135      */
136     long getContentLength();
137
138     /**
139      * Get the last modification date of this source. The date is
140      * measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970),
141      * and is <code>0</code> if it's unknown.
142      *
143      * @return the last modification date or <code>0</code>.
144      */
145     long getLastModified();
146     
147 }
148
Popular Tags