org.apache.excalibur.source
Interface Source

All Known Subinterfaces:

ModifiableSource, ModifiableTraversableSource, MoveableSource, TraversableSource

All Known Implementing Classes:

AbstractSource, CommonsVFSSource, FileSource, FTPSource, HTTPClientSource, ResourceSource, URLSource

public interface Source

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 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 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!

Version:

CVS $Revision: 1.4 $ $Date: 2004/02/28 11:47:26 $

Author:

Avalon Development Team

Method Summary

boolean	exists() Does this source exist ?
long	getContentLength() Get the content length of this source's content or -1 if the length is unknown.
java.io.InputStream	getInputStream() Return an InputStream to read from the source.
long	getLastModified() Get the last modification date of this source.
java.lang.String	getMimeType() Get the mime-type of the content described by this object.
java.lang.String	getScheme() Return the URI scheme identifier, i.e.
java.lang.String	getURI() Get the absolute URI for this source.
SourceValidity	getValidity() Get the Validity object.
void	refresh() Refresh the content of this object after the underlying data content has changed.

Method Detail

exists

public boolean exists()

Does this source exist ?

Returns:

true if the source exists

getInputStream

public java.io.InputStream getInputStream()
                                   throws java.io.IOException,
                                          SourceNotFoundException

Return an InputStream to read from the source. This is the data at the point of invocation of this method, so if this is Modifiable, you might get different content from two different invocations. The returned stream must be closed by the calling code.

Returns:

the InputStream to read data from (never null).

Throws:

java.io.IOException - if some I/O problem occurs.

SourceNotFoundException - if the source doesn't exist.

getURI

public java.lang.String getURI()

Get the absolute URI for this source.

Returns:

the source URI.

getScheme

public java.lang.String getScheme()

Return the URI scheme identifier, i.e. the part preceding the fist ':' in the URI (see RFC 2396).

This scheme can be used to get the SourceFactory responsible for this object.

Returns:

the URI scheme.

getValidity

public SourceValidity getValidity()

Get the Validity object. This can either wrap the last modification date or some expiry information or anything else describing this object's validity.

If it is currently not possible to calculate such an information, null is returned.

Returns:

the validity, or null.

refresh

public void refresh()

Refresh the content of this object after the underlying data content has changed.

Some implementations may cache some values to speedup sucessive calls. Refreshing ensures you get the latest information.

getMimeType

public java.lang.String getMimeType()

Get the mime-type of the content described by this object. If the source is not able to determine the mime-type by itself this can be null.

Returns:

the source's mime-type or null.

getContentLength

public long getContentLength()

Get the content length of this source's content or -1 if the length is unknown.

Returns:

the source's content length or -1.

getLastModified

public long getLastModified()

Get the last modification date of this source. The date is measured in milliseconds since the epoch (00:00:00 GMT, January 1, 1970), and is 0 if it's unknown.

Returns:

the last modification date or 0.