org.apache.commons.vfs.provider
Class AbstractFileObject

java.lang.Object
  org.apache.commons.vfs.provider.AbstractFileObject

All Implemented Interfaces:

FileObject

Direct Known Subclasses:

CompressedFileFileObject, DelegateFileObject, FtpFileObject, HttpFileObject, LocalFile, RamFileObject, SftpFileObject, TarFileObject, UrlFileObject, ZipFileObject

public abstract class AbstractFileObject

extends Object

implements FileObject

A partial file object implementation.

Version:

$Revision: 484648 $ $Date: 2006-12-08 17:18:36 +0100 (Fr, 08 Dez 2006) $

Author:

Adam Murdoch, Gary D. Gregory

Constructor Summary

protected

AbstractFileObject(FileName name, AbstractFileSystem fs)

Method Summary

boolean	canRenameTo(FileObject newfile) Queries the object if a simple rename to the filename of newfile is possible.
protected void	childrenChanged() Deprecated. use childrenChanged(FileName,FileType)
protected void	childrenChanged(FileName childName, FileType newType) Notifies the file that its children have changed.
void	close() Closes this file, and its content.
void	copyFrom(FileObject file, FileSelector selector) Copies another file to this file.
void	createFile() Creates this file, if it does not exist.
void	createFolder() Creates this folder, if it does not exist.
boolean	delete() Deletes this file.
int	delete(FileSelector selector) Deletes this file, and all children.
protected void	doAttach() Attaches this file object to its file resource.
protected void	doCreateFolder() Creates this file as a folder.
protected void	doDelete() Deletes the file.
protected void	doDetach() Detaches this file object from its file resource.
protected Map	doGetAttributes() Returns the attributes of this file.
protected Certificate[]	doGetCertificates() Returns the certificates used to sign this file.
protected abstract long	doGetContentSize() Returns the size of the file content (in bytes).
protected abstract InputStream	doGetInputStream() Creates an input stream to read the file content from.
protected long	doGetLastModifiedTime() Returns the last modified time of this file.
protected OutputStream	doGetOutputStream(boolean bAppend) Creates an output stream to write the file content to.
protected RandomAccessContent	doGetRandomAccessContent(RandomAccessMode mode) Creates access to the file for random i/o.
protected abstract FileType	doGetType() Determines the type of this file.
protected boolean	doIsHidden() Determines if this file is hidden.
protected boolean	doIsReadable() Determines if this file can be read.
protected boolean	doIsSameFile(FileObject destFile) Checks if this fileObject is the same file as destFile just with a different name.
protected boolean	doIsWriteable() Determines if this file can be written to.
protected abstract String[]	doListChildren() Lists the children of this file.
protected FileObject[]	doListChildrenResolved() Lists the children of this file.
protected void	doRename(FileObject newfile) Renames the file.
protected void	doSetAttribute(String atttrName, Object value) Sets an attribute of this file.
protected void	doSetLastModifiedTime(long modtime) Sets the last modified time of this file.
protected void	endOutput() Called when the ouput stream for this file is closed.
boolean	exists() Determines if the file exists.
protected void	finalize()
FileObject[]	findFiles(FileSelector selector) Finds the set of matching descendents of this file, in depthwise order.
void	findFiles(FileSelector selector, boolean depthwise, List selected) Traverses the descendents of this file, and builds a list of selected files.
FileObject	getChild(String name) Returns a child of this file.
FileObject[]	getChildren() Returns the children of the file.
FileContent	getContent() Returns the file's content.
protected FileContentInfoFactory	getFileContentInfoFactory() create the filecontentinfo implementation
FileOperations	getFileOperations()
FileSystem	getFileSystem() Returns the file system this file belongs to.
InputStream	getInputStream() Returns an input stream to use to read the content of the file.
FileName	getName() Returns the name of the file.
OutputStream	getOutputStream() Prepares this file for writing.
OutputStream	getOutputStream(boolean bAppend) Prepares this file for writing.
FileObject	getParent() Returns the parent of the file.
RandomAccessContent	getRandomAccessContent(RandomAccessMode mode) Returns an input/output stream to use to read and write the content of the file in and random manner.
FileType	getType() Returns the file's type.
URL	getURL() Returns a URL representation of the file.
protected void	handleChanged() Called when this file is changed.
protected void	handleCreate(FileType newType) Called when this file is created.
protected void	handleDelete() Called when this file is deleted.
void	holdObject(Object strongRef) This method is meant to add a object where this object holds a strong reference then.
protected void	injectType(FileType fileType)
boolean	isAttached() Check if the internal state is "attached"
boolean	isContentOpen() Check if the content stream is open
boolean	isHidden() Determines if this file can be read.
boolean	isReadable() Determines if this file can be read.
protected boolean	isSameFile(FileObject destFile) Checks if this fileObject is the same file as destFile just with a different name.
boolean	isWriteable() Determines if this file can be written to.
void	moveTo(FileObject destFile) Moves (rename) the file to another one
protected void	notifyAllStreamsClosed() will be called after this file-object closed all its streams.
protected void	onChange() Called when the type or content of this file changes.
protected void	onChildrenChanged(FileName child, FileType newType) Called when the children of this file change.
void	refresh() This will prepare the fileObject to get resynchronized with the underlaying filesystem if required
FileObject	resolveFile(String path) Finds a file, relative to this file.
FileObject	resolveFile(String name, NameScope scope) Returns a child by name.
String	toString() Returns the URI of the file.

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractFileObject

protected AbstractFileObject(FileName name,
                             AbstractFileSystem fs)

Method Detail

doAttach

protected void doAttach()
                 throws Exception

Attaches this file object to its file resource. This method is called before any of the doBlah() or onBlah() methods. Sub-classes can use this method to perform lazy initialisation.

This implementation does nothing.

Throws:

Exception

doDetach

protected void doDetach()
                 throws Exception

Detaches this file object from its file resource.

Called when this file is closed. Note that the file object may be reused later, so should be able to be reattached.

This implementation does nothing.

Throws:

Exception

doGetType

protected abstract FileType doGetType()
                               throws Exception

Determines the type of this file. Must not return null. The return value of this method is cached, so the implementation can be expensive.

Throws:

Exception

doIsHidden

protected boolean doIsHidden()
                      throws Exception

Determines if this file is hidden. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation always returns false.

Throws:

Exception

doIsReadable

protected boolean doIsReadable()
                        throws Exception

Determines if this file can be read. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation always returns true.

Throws:

Exception

doIsWriteable

protected boolean doIsWriteable()
                         throws Exception

Determines if this file can be written to. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation always returns true.

Throws:

Exception

doListChildren

protected abstract String[] doListChildren()
                                    throws Exception

Lists the children of this file. Is only called if doGetType() returns FileType.FOLDER. The return value of this method is cached, so the implementation can be expensive.

Throws:

Exception

doListChildrenResolved

protected FileObject[] doListChildrenResolved()
                                       throws Exception

Lists the children of this file. Is only called if doGetType() returns FileType.FOLDER. The return value of this method is cached, so the implementation can be expensive.
Other than doListChildren you could return FileObject's to e.g. reinitialize the type of the file.
(Introduced for Webdav: "permission denied on resource" during getType())

Throws:

Exception

doDelete

protected void doDelete()
                 throws Exception

Deletes the file. Is only called when:

• doGetType() does not return FileType.IMAGINARY.
• doIsWriteable() returns true.
• This file has no children, if a folder.

This implementation throws an exception.

Throws:

Exception

doRename

protected void doRename(FileObject newfile)
                 throws Exception

Renames the file. Is only called when:

• doIsWriteable() returns true.

This implementation throws an exception.

Throws:

Exception

doCreateFolder

protected void doCreateFolder()
                       throws Exception

Creates this file as a folder. Is only called when:

• doGetType() returns FileType.IMAGINARY.
• The parent folder exists and is writeable, or this file is the root of the file system.

This implementation throws an exception.

Throws:

Exception

onChildrenChanged

protected void onChildrenChanged(FileName child,
                                 FileType newType)
                          throws Exception

Called when the children of this file change. Allows subclasses to refresh any cached information about the children of this file.

This implementation does nothing.

Throws:

Exception

onChange

protected void onChange()
                 throws Exception

Called when the type or content of this file changes.

This implementation does nothing.

Throws:

Exception

doGetLastModifiedTime

protected long doGetLastModifiedTime()
                              throws Exception

Returns the last modified time of this file. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation throws an exception.

Throws:

Exception

doSetLastModifiedTime

protected void doSetLastModifiedTime(long modtime)
                              throws Exception

Sets the last modified time of this file. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation throws an exception.

Throws:

Exception

doGetAttributes

protected Map doGetAttributes()
                       throws Exception

Returns the attributes of this file. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation always returns an empty map.

Throws:

Exception

doSetAttribute

protected void doSetAttribute(String atttrName,
                              Object value)
                       throws Exception

Sets an attribute of this file. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation throws an exception.

Throws:

Exception

doGetCertificates

protected Certificate[] doGetCertificates()
                                   throws Exception

Returns the certificates used to sign this file. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation always returns null.

Throws:

Exception

doGetContentSize

protected abstract long doGetContentSize()
                                  throws Exception

Returns the size of the file content (in bytes). Is only called if doGetType() returns FileType.FILE.

Throws:

Exception

doGetInputStream

protected abstract InputStream doGetInputStream()
                                         throws Exception

Creates an input stream to read the file content from. Is only called if doGetType() returns FileType.FILE.

It is guaranteed that there are no open output streams for this file when this method is called.

The returned stream does not have to be buffered.

Throws:

Exception

doGetRandomAccessContent

protected RandomAccessContent doGetRandomAccessContent(RandomAccessMode mode)
                                                throws Exception

Creates access to the file for random i/o. Is only called if doGetType() returns FileType.FILE.

It is guaranteed that there are no open output streams for this file when this method is called.

Throws:

Exception

doGetOutputStream

protected OutputStream doGetOutputStream(boolean bAppend)
                                  throws Exception

Creates an output stream to write the file content to. Is only called if:

• doIsWriteable() returns true.
• doGetType() returns FileType.FILE, or doGetType() returns FileType.IMAGINARY, and the file's parent exists and is a folder.

It is guaranteed that there are no open stream (input or output) for this file when this method is called.

The returned stream does not have to be buffered.

This implementation throws an exception.

Throws:

Exception

toString

public String toString()

Returns the URI of the file.

getName

public FileName getName()

Returns the name of the file.

Specified by:

getName in interface FileObject

getFileSystem

public FileSystem getFileSystem()

Returns the file system this file belongs to.

Specified by:

getFileSystem in interface FileObject

Returns:

The file system.

getURL

public URL getURL()
           throws FileSystemException

Returns a URL representation of the file.

Specified by:

getURL in interface FileObject

Throws:

FileSystemException

exists

public boolean exists()
               throws FileSystemException

Determines if the file exists.

Specified by:

exists in interface FileObject

Returns:

true if this file exists, false if not.

Throws:

FileSystemException - On error determining if this file exists.

getType

public FileType getType()
                 throws FileSystemException

Returns the file's type.

Specified by:

getType in interface FileObject

Returns:

One of the FileType constants. Never returns null.

Throws:

FileSystemException - On error determining the file's type.

isHidden

public boolean isHidden()
                 throws FileSystemException

Determines if this file can be read.

Specified by:

isHidden in interface FileObject

Returns:

true if this file is hidden, false if not.

Throws:

FileSystemException - On error determining if this file exists.

isReadable

public boolean isReadable()
                   throws FileSystemException

Determines if this file can be read.

Specified by:

isReadable in interface FileObject

Returns:

true if this file is readable, false if not.

Throws:

FileSystemException - On error determining if this file exists.

isWriteable

public boolean isWriteable()
                    throws FileSystemException

Determines if this file can be written to.

Specified by:

isWriteable in interface FileObject

Returns:

true if this file is writeable, false if not.

Throws:

FileSystemException - On error determining if this file exists.

getParent

public FileObject getParent()
                     throws FileSystemException

Returns the parent of the file.

Specified by:

getParent in interface FileObject

Returns:

The folder that contains this file. Returns null if this file is the root of a file system.

Throws:

FileSystemException - On error finding the file's parent.

getChildren

public FileObject[] getChildren()
                         throws FileSystemException

Returns the children of the file.

Specified by:

getChildren in interface FileObject

Returns:

An array containing the children of this file. The array is unordered. If the file does not have any children, a zero-length array is returned. This method never returns null.

Throws:

FileSystemException - If this file does not exist, or is not a folder, or on error listing this file's children.

getChild

public FileObject getChild(String name)
                    throws FileSystemException

Returns a child of this file.

Specified by:

getChild in interface FileObject

Parameters:

name - The name of the child.

Returns:

The child, or null if there is no such child.

Throws:

FileSystemException - If this file does not exist, or is not a folder, or on error determining this file's children.

resolveFile

public FileObject resolveFile(String name,
                              NameScope scope)
                       throws FileSystemException

Returns a child by name.

Specified by:

resolveFile in interface FileObject

Parameters:

name - The name to resolve.

Returns:

The file.

Throws:

FileSystemException - On error parsing the path, or on error finding the file.

resolveFile

public FileObject resolveFile(String path)
                       throws FileSystemException

Finds a file, relative to this file.

Specified by:

resolveFile in interface FileObject

Parameters:

path - The path of the file to locate. Can either be a relative path, which is resolved relative to this file, or an absolute path, which is resolved relative to the file system that contains this file.

Returns:

The file.

Throws:

FileSystemException - On error parsing the path, or on error finding the file.

delete

public boolean delete()
               throws FileSystemException

Deletes this file.

Specified by:

delete in interface FileObject

Returns:

true if this object has been deleted

Throws:

FileSystemException - If this file is a non-empty folder, or if this file is read-only, or on error deleteing this file.

delete

public int delete(FileSelector selector)
           throws FileSystemException

Deletes this file, and all children.

Specified by:

delete in interface FileObject

Parameters:

selector - The selector to use to select which files to delete.

Returns:

the number of deleted files

Throws:

FileSystemException - If this file or one of its descendents is read-only, or on error deleting this file or one of its descendents.

createFile

public void createFile()
                throws FileSystemException

Creates this file, if it does not exist.

Specified by:

createFile in interface FileObject

Throws:

FileSystemException - If the file already exists with the wrong type, or the parent folder is read-only, or on error creating this file or one of its ancestors.

createFolder

public void createFolder()
                  throws FileSystemException

Creates this folder, if it does not exist. Also creates any ancestor files which do not exist.

Specified by:

createFolder in interface FileObject

Throws:

FileSystemException - If the folder already exists with the wrong type, or the parent folder is read-only, or on error creating this folder or one of its ancestors.

copyFrom

public void copyFrom(FileObject file,
                     FileSelector selector)
              throws FileSystemException

Copies another file to this file.

Specified by:

copyFrom in interface FileObject

Parameters:

file - The source file to copy.

selector - The selector to use to select which files to copy.

Throws:

FileSystemException - If this file is read-only, or if the source file does not exist, or on error copying the file.

moveTo

public void moveTo(FileObject destFile)
            throws FileSystemException

Moves (rename) the file to another one

Specified by:

moveTo in interface FileObject

Parameters:

destFile - the New filename.

Throws:

FileSystemException - If this file is read-only, or if the source file does not exist, or on error copying the file.

isSameFile

protected boolean isSameFile(FileObject destFile)
                      throws FileSystemException

Checks if this fileObject is the same file as destFile just with a different name.
E.g. for case insensitive filesystems like windows.

Throws:

FileSystemException

doIsSameFile

protected boolean doIsSameFile(FileObject destFile)
                        throws FileSystemException

Checks if this fileObject is the same file as destFile just with a different name.
E.g. for case insensitive filesystems like windows.

Throws:

FileSystemException

canRenameTo

public boolean canRenameTo(FileObject newfile)

Queries the object if a simple rename to the filename of newfile is possible.

Specified by:

canRenameTo in interface FileObject

Parameters:

newfile - the new filename

Returns:

true if rename is possible

findFiles

public FileObject[] findFiles(FileSelector selector)
                       throws FileSystemException

Finds the set of matching descendents of this file, in depthwise order.

Specified by:

findFiles in interface FileObject

Parameters:

selector - The selector to use to select matching files.

Returns:

list of files or null if the base file (this object) do not exist

Throws:

FileSystemException

getContent

public FileContent getContent()
                       throws FileSystemException

Returns the file's content.

Specified by:

getContent in interface FileObject

Returns:

This file's content.

Throws:

FileSystemException - On error getting this file's content.

refresh

public void refresh()
             throws FileSystemException

This will prepare the fileObject to get resynchronized with the underlaying filesystem if required

Specified by:

refresh in interface FileObject

Throws:

FileSystemException

close

public void close()
           throws FileSystemException

Closes this file, and its content.

Specified by:

close in interface FileObject

Throws:

FileSystemException - On error closing the file.

See Also:

FileContent.close()

getInputStream

public InputStream getInputStream()
                           throws FileSystemException

Returns an input stream to use to read the content of the file.

Throws:

FileSystemException

getRandomAccessContent

public RandomAccessContent getRandomAccessContent(RandomAccessMode mode)
                                           throws FileSystemException

Returns an input/output stream to use to read and write the content of the file in and random manner.

Throws:

FileSystemException

getOutputStream

public OutputStream getOutputStream()
                             throws FileSystemException

Prepares this file for writing. Makes sure it is either a file, or its parent folder exists. Returns an output stream to use to write the content of the file to.

Throws:

FileSystemException

getOutputStream

public OutputStream getOutputStream(boolean bAppend)
                             throws FileSystemException

Prepares this file for writing. Makes sure it is either a file, or its parent folder exists. Returns an output stream to use to write the content of the file to.

Parameters:

bAppend - true when append to the file.
Note: If the underlaying filesystem do not support this, it wont work.

Throws:

FileSystemException

endOutput

protected void endOutput()
                  throws Exception

Called when the ouput stream for this file is closed.

Throws:

Exception

handleCreate

protected void handleCreate(FileType newType)
                     throws Exception

Called when this file is created. Updates cached info and notifies the parent and file system.

Throws:

Exception

handleDelete

protected void handleDelete()
                     throws Exception

Called when this file is deleted. Updates cached info and notifies subclasses, parent and file system.

Throws:

Exception

handleChanged

protected void handleChanged()
                      throws Exception

Called when this file is changed.
This will only happen if you monitor the file using FileMonitor.

Throws:

Exception

childrenChanged

protected void childrenChanged()
                        throws Exception

Deprecated. use childrenChanged(FileName,FileType)

Notifies the file that its children have changed.

Throws:

Exception

childrenChanged

protected void childrenChanged(FileName childName,
                               FileType newType)
                        throws Exception

Notifies the file that its children have changed.

Throws:

Exception

findFiles

public void findFiles(FileSelector selector,
                      boolean depthwise,
                      List selected)
               throws FileSystemException

Traverses the descendents of this file, and builds a list of selected files.

Specified by:

findFiles in interface FileObject

Parameters:

selector - the selector used to determine if the file should be selected

depthwise - controls the ordering in the list. e.g. deepest first

selected - container for selected files. list needs not to be empty.

Throws:

FileSystemException

isContentOpen

public boolean isContentOpen()

Check if the content stream is open

Specified by:

isContentOpen in interface FileObject

Returns:

true if this is the case

isAttached

public boolean isAttached()

Check if the internal state is "attached"

Specified by:

isAttached in interface FileObject

Returns:

true if this is the case

getFileContentInfoFactory

protected FileContentInfoFactory getFileContentInfoFactory()

create the filecontentinfo implementation

injectType

protected void injectType(FileType fileType)

holdObject

public void holdObject(Object strongRef)

This method is meant to add a object where this object holds a strong reference then. E.g. a archive-filesystem creates a list of all childs and they shouldnt get garbage collected until the container is garbage collected

Parameters:

strongRef -

notifyAllStreamsClosed

protected void notifyAllStreamsClosed()

will be called after this file-object closed all its streams.

getFileOperations

public FileOperations getFileOperations()
                                 throws FileSystemException

Specified by:

getFileOperations in interface FileObject

Returns:

FileOperations interface that provides access to the operations API.

Throws:

FileSystemException

finalize

protected void finalize()
                 throws Throwable

Throws:

Throwable