This interface provides a simple interface for accessing a source of data.
When the Source
object is no longer needed it must be released using the {@link SourceResolver}. This is very similar to looking up components from a ServiceSelector
. In fact a source object can implement most lifecycle interfaces like Composable, Initializable, Disposable etc.
The data content can be constant or change over time. Using the {@link #getInputStream()} method you get always the up-to-date content.
If you want to track changes of the source object, this interface offers you some support for it by providing a SourceValidity object.
How does the caching work? The first time you get a Source object, you simply ask it for it's content via getInputStream() and then get the validity object by invoking getValidity. (Further calls to getValidity always return the same object! This is not updated!) The caching algorithm can now store this validity object together with the system identifier of the source. The next time, the caching algorithm wants to check if the cached content is still valid. It has a validity object already to check against.
If it is still the same Source than the first time, you have to call refresh() in order to discard the stored validity in the Source object. If it is a new Source object, calling refresh() should do no harm. After that an up-to-date validity object can retrieved by calling getValidity(). This can be used to test if the content is still valid as discribed in the source validity documentation. If the content is still valid, the cache knows what to do, if not, the new content can be get using getInputStream(). So either after a call to getValidity() or the getInputStream the validity object must be the same until refresh is called!
@author Avalon Development Team
@version CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:26 $