org.apache.excalibur.source.impl
Class FileSource

java.lang.Object
  org.apache.excalibur.source.impl.FileSource

All Implemented Interfaces:

ModifiableSource, ModifiableTraversableSource, MoveableSource, Source, TraversableSource

public class FileSource

extends java.lang.Object

implements ModifiableTraversableSource, MoveableSource

A ModifiableTraversableSource for filesystem objects.

Version:

$Id: FileSource.java,v 1.5 2004/02/28 11:47:24 cziegeler Exp $

Author:

Avalon Development Team

Constructor Summary

FileSource(java.lang.String uri)
Builds a FileSource given an URI, which doesn't necessarily have to start with "file:"

FileSource(java.lang.String scheme, java.io.File file)
Builds a FileSource, given an URI scheme and a File.

Method Summary

boolean	canCancel(java.io.OutputStream stream) Can the data sent to an OutputStream returned by getOutputStream() be cancelled ?
void	cancel(java.io.OutputStream stream) Cancel the data sent to an OutputStream returned by getOutputStream().
void	copyTo(Source destination) Copy the current source to a specified destination.
void	delete() Delete the source.
boolean	exists() Does this source actually exist ?
Source	getChild(java.lang.String name) Get a child of this source, given its name.
java.util.Collection	getChildren() Get the children of this source if this source is traversable.
long	getContentLength() Get the content length of this source's content or -1 if the length is unknown.
java.io.File	getFile() Get the associated file
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	getName() Return the name of this source relative to its parent.
java.io.OutputStream	getOutputStream() Get an InputStream where raw bytes can be written to.
Source	getParent() Get the parent of this source as a Source 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() Return a validity object based on the file's modification date.
boolean	isCollection() Is this source a collection, i.e.
void	makeCollection() If it doesn't already exist, ensure this source is traversable (equivalent to File.mkdirs())
void	moveTo(Source destination) Move the current source to a specified destination.
void	refresh() Refresh the content of this object after the underlying data content has changed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

FileSource

public FileSource(java.lang.String uri)
           throws SourceException,
                  java.net.MalformedURLException

Builds a FileSource given an URI, which doesn't necessarily have to start with "file:"

Parameters:

uri -

Throws:

SourceException

java.net.MalformedURLException

FileSource

public FileSource(java.lang.String scheme,
                  java.io.File file)
           throws SourceException

Builds a FileSource, given an URI scheme and a File.

Parameters:

scheme -

file -

Throws:

SourceException

Method Detail

getFile

public java.io.File getFile()

Get the associated file

getContentLength

public long getContentLength()

Description copied from interface: Source

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

Specified by:

getContentLength in interface Source

Returns:

the source's content length or -1.

See Also:

Source.getContentLength()

getInputStream

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

Description copied from interface: Source

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.

Specified by:

getInputStream in interface Source

Returns:

the InputStream to read data from (never null).

Throws:

SourceNotFoundException - if the source doesn't exist.

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

See Also:

Source.getInputStream()

getLastModified

public long getLastModified()

Description copied from interface: Source

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.

Specified by:

getLastModified in interface Source

Returns:

the last modification date or 0.

See Also:

Source.getLastModified()

getMimeType

public java.lang.String getMimeType()

Description copied from interface: Source

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.

Specified by:

getMimeType in interface Source

Returns:

the source's mime-type or null.

See Also:

Source.getMimeType()

getScheme

public java.lang.String getScheme()

Description copied from interface: Source

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.

Specified by:

getScheme in interface Source

Returns:

the URI scheme.

getURI

public java.lang.String getURI()

Description copied from interface: Source

Get the absolute URI for this source.

Specified by:

getURI in interface Source

Returns:

the source URI.

getValidity

public SourceValidity getValidity()

Return a validity object based on the file's modification date.

Specified by:

getValidity in interface Source

Returns:

the validity, or null.

See Also:

Source.getValidity()

refresh

public void refresh()

Description copied from interface: Source

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.

Specified by:

refresh in interface Source

See Also:

Source.refresh()

exists

public boolean exists()

Does this source actually exist ?

Specified by:

exists in interface Source

Returns:

true if the resource exists.

getChild

public Source getChild(java.lang.String name)
                throws SourceException

Description copied from interface: TraversableSource

Get a child of this source, given its name. Note that the returned source may not actually physically exist, and that this must be checked using Source.exists().

Specified by:

getChild in interface TraversableSource

Parameters:

name - the child name.

Returns:

the child source.

Throws:

SourceException - if this source is not traversable or if some other error occurs.

See Also:

TraversableSource.getChild(java.lang.String)

getChildren

public java.util.Collection getChildren()
                                 throws SourceException

Description copied from interface: TraversableSource

Get the children of this source if this source is traversable.

Note: only those sources actually fetched from the collection need to be released using the SourceResolver.

Specified by:

getChildren in interface TraversableSource

Returns:

a collection of Sources (actually most probably TraversableSources).

Throws:

SourceException - this source is not traversable, or if some problem occurs.

See Also:

TraversableSource.getChildren()

getName

public java.lang.String getName()

Description copied from interface: TraversableSource

Return the name of this source relative to its parent.

Specified by:

getName in interface TraversableSource

Returns:

the name

See Also:

TraversableSource.getName()

getParent

public Source getParent()
                 throws SourceException

Description copied from interface: TraversableSource

Get the parent of this source as a Source object.

Specified by:

getParent in interface TraversableSource

Returns:

the parent source, or null if this source has no parent.

Throws:

SourceException - if some problem occurs.

See Also:

TraversableSource.getParent()

isCollection

public boolean isCollection()

Description copied from interface: TraversableSource

Is this source a collection, i.e. it possibly has children ? For a filesystem-based implementation, this would typically mean that this source represents a directory and not a file.

Specified by:

isCollection in interface TraversableSource

Returns:

true if the source exists and is traversable.

See Also:

TraversableSource.isCollection()

getOutputStream

public java.io.OutputStream getOutputStream()
                                     throws java.io.IOException

Get an InputStream where raw bytes can be written to. The signification of these bytes is implementation-dependent and is not restricted to a serialized XML document. The output stream returned actually writes to a temp file that replaces the real one on close. This temp file is used as lock to forbid multiple simultaneous writes. The real file is updated atomically when the output stream is closed. The returned stream must be closed or cancelled by the calling code.

Specified by:

getOutputStream in interface ModifiableSource

Returns:

a stream to write to

Throws:

java.util.ConcurrentModificationException - if another thread is currently writing to this file.

java.io.IOException

canCancel

public boolean canCancel(java.io.OutputStream stream)

Can the data sent to an OutputStream returned by getOutputStream() be cancelled ?

Specified by:

canCancel in interface ModifiableSource

Returns:

true if the stream can be cancelled

cancel

public void cancel(java.io.OutputStream stream)
            throws SourceException

Cancel the data sent to an OutputStream returned by getOutputStream().

After cancel, the stream should no more be used.

Specified by:

cancel in interface ModifiableSource

Throws:

SourceException

delete

public void delete()
            throws SourceException

Delete the source.

Specified by:

delete in interface ModifiableSource

Throws:

SourceException

makeCollection

public void makeCollection()
                    throws SourceException

Description copied from interface: ModifiableTraversableSource

If it doesn't already exist, ensure this source is traversable (equivalent to File.mkdirs())

If the source already exists, this method does nothing if it's already traversable, and fails otherwise.

Specified by:

makeCollection in interface ModifiableTraversableSource

Throws:

SourceException

See Also:

ModifiableTraversableSource.makeCollection()

copyTo

public void copyTo(Source destination)
            throws SourceException

Description copied from interface: MoveableSource

Copy the current source to a specified destination.

Specified by:

copyTo in interface MoveableSource

Parameters:

destination - Destination of the source.

Throws:

SourceException - If an exception occurs during the copy.

See Also:

MoveableSource.copyTo(org.apache.excalibur.source.Source)

moveTo

public void moveTo(Source destination)
            throws SourceException

Description copied from interface: MoveableSource

Move the current source to a specified destination.

Specified by:

moveTo in interface MoveableSource

Parameters:

destination - Destination of the source.

Throws:

SourceException - If an exception occurs during the move.

See Also:

MoveableSource.moveTo(org.apache.excalibur.source.Source)