org.apache.commons.vfs2.provider
Class AbstractFileObject

java.lang.Object
  extended by org.apache.commons.vfs2.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.

Author:
Commons VFS team
To Do:
Chop this class up - move all the protected methods to several interfaces, so that structure and content can be separately overridden., Check caps in methods like getChildren(), etc, and give better error messages (eg 'this file type does not support listing children', vs 'this is not a folder')

Constructor Summary
protected AbstractFileObject(AbstractFileName 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(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  FileContent doCreateFileContent()
          Create a FileContent implementation.
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<String,Object> 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.
E.g.
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 doRemoveAttribute(String attrName)
          Removes an attribute of this file.
protected  void doRename(FileObject newfile)
          Renames the file.
protected  void doSetAttribute(String attrName, Object value)
          Sets an attribute of this file.
protected  boolean 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<FileObject> 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.
This will only happen if you monitor the file using FileMonitor.
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 an 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.
E.g.
 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(AbstractFileName name,
                             AbstractFileSystem fs)
Parameters:
name - the file name - muse be an instance of AbstractFileName
fs - the file system
Throws:
ClassCastException - if name is not an instance of AbstractFileName
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 - if an error occurs.

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 - if an error occurs.

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.

Returns:
the type of the file.
Throws:
Exception - if an error occurs.

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.

Returns:
true if the file is hidden, false otherwise.
Throws:
Exception - if an error occurs.

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.

Returns:
true if the file is readable, false otherwise.
Throws:
Exception - if an error occurs.

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.

Returns:
true if the file is writable.
Throws:
Exception - if an error occurs.

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.

Returns:
a possible empty String array if the file is a directory or null or an exception if the file is not a directory or can't be read.
Throws:
Exception - if an error occurs.

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())

Returns:
The children of this FileObject.
Throws:
Exception - if an error occurs.

doDelete

protected void doDelete()
                 throws Exception
Deletes the file. Is only called when:

This implementation throws an exception.

Throws:
Exception - if an error occurs.

doRename

protected void doRename(FileObject newfile)
                 throws Exception
Renames the file. Is only called when:

This implementation throws an exception.

Parameters:
newfile - A FileObject with the new file name.
Throws:
Exception - if an error occurs.

doCreateFolder

protected void doCreateFolder()
                       throws Exception
Creates this file as a folder. Is only called when:

This implementation throws an exception.

Throws:
Exception - if an error occurs.

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.

Parameters:
child - The name of the child that changed.
newType - The type of the file.
Throws:
Exception - if an error occurs.

onChange

protected void onChange()
                 throws Exception
Called when the type or content of this file changes.

This implementation does nothing.

Throws:
Exception - if an error occurs.

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.

Returns:
The last modification time.
Throws:
Exception - if an error occurs.

doSetLastModifiedTime

protected boolean 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.

Parameters:
modtime - The last modification time.
Returns:
true if the time was set.
Throws:
Exception - if an error occurs.

doGetAttributes

protected Map<String,Object> 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.

Returns:
The attributes of the file.
Throws:
Exception - if an error occurs.

doSetAttribute

protected void doSetAttribute(String attrName,
                              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.

Parameters:
attrName - The attribute name.
value - The value to be associated with the attribute name.
Throws:
Exception - if an error occurs.

doRemoveAttribute

protected void doRemoveAttribute(String attrName)
                          throws Exception
Removes an attribute of this file. Is only called if doGetType() does not return FileType.IMAGINARY.

This implementation throws an exception.

Parameters:
attrName - The name of the attribute to remove.
Throws:
Exception - if an error occurs.
Since:
2.0

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.

Returns:
The certificates used to sign the file.
Throws:
Exception - if an error occurs.

doGetContentSize

protected abstract long doGetContentSize()
                                  throws Exception
Returns the size of the file content (in bytes). Is only called if doGetType() returns FileType.FILE.

Returns:
The size of the file in bytes.
Throws:
Exception - if an error occurs.

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.

Returns:
An InputStream to read the file content.
Throws:
Exception - if an error occurs.

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.

Parameters:
mode - The mode to access the file.
Returns:
The RandomAccessContext.
Throws:
Exception - if an error occurs.

doGetOutputStream

protected OutputStream doGetOutputStream(boolean bAppend)
                                  throws Exception
Creates an output stream to write the file content to. Is only called if:

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.

Parameters:
bAppend - true if the file should be appended to, false if it should be overwritten.
Returns:
An OutputStream to write to the file.
Throws:
Exception - if an error occurs.

toString

public String toString()
Returns the URI of the file.

Overrides:
toString in class Object
Returns:
The URI of the file.

getName

public FileName getName()
Returns the name of the file.

Specified by:
getName in interface FileObject
Returns:
The FileName.

getFileSystem

public FileSystem getFileSystem()
Returns the file system this file belongs to.

Specified by:
getFileSystem in interface FileObject
Returns:
The FileSystem this file is associated with.

getURL

public URL getURL()
           throws FileSystemException
Returns a URL representation of the file.

Specified by:
getURL in interface FileObject
Returns:
The URL representation of the file.
Throws:
FileSystemException - if an error occurs.

exists

public boolean exists()
               throws FileSystemException
Determines if the file exists.

Specified by:
exists in interface FileObject
Returns:
true if the file exists, false otherwise,
Throws:
FileSystemException - if an error occurs.

getType

public FileType getType()
                 throws FileSystemException
Returns the file's type.

Specified by:
getType in interface FileObject
Returns:
The FileType.
Throws:
FileSystemException - if an error occurs.

isHidden

public boolean isHidden()
                 throws FileSystemException
Determines if this file can be read.

Specified by:
isHidden in interface FileObject
Returns:
true if the file is a hidden file, false otherwise.
Throws:
FileSystemException - if an error occurs.

isReadable

public boolean isReadable()
                   throws FileSystemException
Determines if this file can be read.

Specified by:
isReadable in interface FileObject
Returns:
true if the file can be read, false otherwise.
Throws:
FileSystemException - if an error occurs.

isWriteable

public boolean isWriteable()
                    throws FileSystemException
Determines if this file can be written to.

Specified by:
isWriteable in interface FileObject
Returns:
true if the file can be written to, false otherwise.
Throws:
FileSystemException - if an error occurs.

getParent

public FileObject getParent()
                     throws FileSystemException
Returns the parent of the file.

Specified by:
getParent in interface FileObject
Returns:
the parent FileObject.
Throws:
FileSystemException - if an error occurs.

getChildren

public FileObject[] getChildren()
                         throws FileSystemException
Returns the children of the file.

Specified by:
getChildren in interface FileObject
Returns:
an array of FileObjects, one per child.
Throws:
FileSystemException - if an error occurs.

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 to locate.
Returns:
The FileObject for the file or null if the child does not exist.
Throws:
FileSystemException - if an error occurs.

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 of the child to locate.
scope - the NameScope.
Returns:
The FileObject for the file or null if the child does not exist.
Throws:
FileSystemException - if an error occurs.

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 FileObject.
Throws:
FileSystemException - if an error occurs.

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 an error occurs.
To Do:
This will not fail if this is a non-empty folder.

delete

public int delete(FileSelector selector)
           throws FileSystemException
Deletes this file, and all children.

Specified by:
delete in interface FileObject
Parameters:
selector - The FileSelector.
Returns:
the number of deleted files.
Throws:
FileSystemException - if an error occurs.

createFile

public void createFile()
                throws FileSystemException
Creates this file, if it does not exist.

Specified by:
createFile in interface FileObject
Throws:
FileSystemException - if an error occurs.

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 an error occurs.

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 FileObject to copy.
selector - The FileSelector.
Throws:
FileSystemException - if an error occurs.

moveTo

public void moveTo(FileObject destFile)
            throws FileSystemException
Moves (rename) the file to another one.

Specified by:
moveTo in interface FileObject
Parameters:
destFile - The target FileObject.
Throws:
FileSystemException - if an error occurs.

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.

Parameters:
destFile - The file to compare to.
Returns:
true if the FileObjects are the same.
Throws:
FileSystemException - if an error occurs.

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.

Parameters:
destFile - The file to compare to.
Returns:
true if the FileObjects are the same.
Throws:
FileSystemException - if an error occurs.

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 FileSelector.
Returns:
list of files or null if the base file (this object) do not exist
Throws:
FileSystemException - if an error occurs.

getContent

public FileContent getContent()
                       throws FileSystemException
Returns the file's content.

Specified by:
getContent in interface FileObject
Returns:
the FileContent for this FileObject.
Throws:
FileSystemException - if an error occurs.

doCreateFileContent

protected FileContent doCreateFileContent()
                                   throws FileSystemException
Create a FileContent implementation.

Returns:
The FileContent.
Throws:
FileSystemException - if an error occurs.
Since:
2.0

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 - if an error occurs.

close

public void close()
           throws FileSystemException
Closes this file, and its content.

Specified by:
close in interface FileObject
Throws:
FileSystemException - if an error occurs.
See Also:
FileContent.close()

getInputStream

public InputStream getInputStream()
                           throws FileSystemException
Returns an input stream to use to read the content of the file.

Returns:
The InputStream to access this file's content.
Throws:
FileSystemException - if an error occurs.

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.

Parameters:
mode - The RandomAccessMode.
Returns:
The RandomAccessContent.
Throws:
FileSystemException - if an error occurs.

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.

Returns:
An OutputStream where the new contents of the file can be written.
Throws:
FileSystemException - if an error occurs.

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.
Returns:
An OutputStream where the new contents of the file can be written.
Throws:
FileSystemException - if an error occurs.

endOutput

protected void endOutput()
                  throws Exception
Called when the ouput stream for this file is closed.

Throws:
Exception - if an error occurs.

handleCreate

protected void handleCreate(FileType newType)
                     throws Exception
Called when this file is created. Updates cached info and notifies the parent and file system.

Parameters:
newType - The type of the file.
Throws:
Exception - if an error occurs.

handleDelete

protected void handleDelete()
                     throws Exception
Called when this file is deleted. Updates cached info and notifies subclasses, parent and file system.

Throws:
Exception - if an error occurs.

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 - if an error occurs.

childrenChanged

protected void childrenChanged(FileName childName,
                               FileType newType)
                        throws Exception
Notifies the file that its children have changed.

Parameters:
childName - The name of the child.
newType - The type of the child.
Throws:
Exception - if an error occurs.

findFiles

public void findFiles(FileSelector selector,
                      boolean depthwise,
                      List<FileObject> 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 FileSelector.
depthwise - if true files are added after their descendants, before otherwise.
selected - A List of the located FileObjects.
Throws:
FileSystemException - if an error occurs.

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.

Returns:
The FileContentInfoFactory.

injectType

protected void injectType(FileType fileType)

holdObject

public void holdObject(Object strongRef)
This method is meant to add an 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 - The Object to add.

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 - if an error occurs.

finalize

protected void finalize()
                 throws Throwable
Overrides:
finalize in class Object
Throws:
Throwable


Copyright © 2002-2012 The Apache Software Foundation. All Rights Reserved.